Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mise-en-place what are the macros for 4 oz raw chicken breast?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that returns trustworthy macronutrient data for a named ingredient at a named quantity, sourced from USDA FoodData Central.
It has one job: when an LLM is planning a meal or building a recipe, give it real calories/protein/carbs/fat for a real food at a real quantity, never a plausible-sounding guess. Composition, recipe design, and arithmetic stay the calling model's problem. Correct inputs are this server's only problem.
mise-en-place is not a nutrition database of its own. It's a lookup layer
in front of USDA FoodData Central, built so an
LLM can search for a food, resolve a quantity ("1 medium onion", "2
tablespoons", "6 oz") to grams, and get back real, sourced macros instead of
inventing one. It runs over MCP (stdio), so any MCP-capable client (Claude
Code, Claude Desktop, or anything else that speaks the protocol) can connect
to it directly.
Eight tools: search_foods, get_nutrition, get_nutrition_batch,
save_override, save_recipe, get_recipe, get_recipe_history,
list_recipes. Full signatures and schemas are in INTERFACES.md.
Related MCP server: Food Data Central MCP Server
Requirements: Python 3.11+, a free USDA FoodData Central API key (instant signup).
git clone <this repo>
cd mise-en-place
uv sync # or: pip install -e .
export USDA_API_KEY=<your key>Register it with an MCP client, e.g. Claude Code:
claude mcp add mise-en-place -s local -e USDA_API_KEY=<your key> -- \
uv run --directory /path/to/mise-en-place mise-en-placeRestart the client so it picks up the new connection, then just ask for what
you're cooking. The server's own instructions (visible in server.py's
_SERVER_INSTRUCTIONS) travel with the connection and tell the model how to
use the tools correctly, so nothing needs to be pasted into the chat by hand.
If you're running recurring meal-planning sessions with your own macro
targets, see MEAL_PLANNING_PROMPT.md. Targets are per-person and
per-meal, so the server never stores them; that one file is where they live.
Personal corrections and saved recipes live in ~/.mise-en-place/
(MISE_HOME), never committed. masses.toml at the repo root is the one
shipped, checked-in default table of common household-measure weights (a
medium onion, a large egg): human-written, cited, and safe to disagree with
by editing it.
A lot of "get me the calories" tools answer a question they don't actually know the answer to. This one doesn't:
Never invents a nutrient value. If USDA doesn't have the number, the tool raises or reports it as explicitly absent, never a zero and never an estimate standing in for a fact.
Never falls back to a round number. A quantity that can't be resolved
to a mass (through USDA's own portion data, your own saved corrections, or
the shipped masses.toml defaults) raises instead of defaulting to 100g
or guessing a density.
Every uncertain value says so, out loud. A low-confidence match, a candidate the tool wasn't sure about, an assumed mass: all of it rides back to the calling model as a structured caveat, not a number that looks exactly as confident as a verified one.
Corrections make the tool better, permanently. save_override and
save_recipe mean a mistake gets fixed once, not re-guessed on every
future lookup of the same ingredient.
Measurably more accurate than a model guessing on its own. A 10-recipe benchmark against hand-verified label data put this tool's mean error at 4.99%, against 8.26% for the same model with no tool access. Methodology and the current number are below.
The rule "never invent a value" is easy to claim and easy to quietly violate. Two things back it up.
Live, re-verified test data. Every USDA ID this project cites, in
masses.toml and in the test suite's golden values, is re-fetched from the
real API on every run and checked against what it's claimed to be
(tests/test_golden_values.py, tests/test_masses_toml.py). A citation
that's gone stale fails loudly instead of sitting there looking authoritative.
Accuracy validated against real product data, not another recipe site's opinion. An early accuracy pass compared this tool's output against a popular health-recipe site's published nutrition figures and found the tool diverging by a lot on some recipes. A closer look showed the divergence ran the other way: hand-checking the worst cases against actual product nutrition labels showed this tool's numbers were the ones close to reality, and the third-party site's were the outlier. Comparing against any recipe site turned out to be the wrong test, since its own methodology is opaque and there's no way to know what product it priced, what serving-yield convention it used, or what nutrition database sits behind it.
The real accuracy benchmark this points toward (tests/golden_recipes/) is
built from two sources deliberately kept apart: USDA data for genuine
commodity ingredients (a potato, granulated sugar: nothing with a brand to
speak of), and real product nutrition labels for anything a specific
commercial product plausibly means (a brand of tortilla, a packaged
tofu). Using USDA data to validate a USDA-backed tool's generic matches
would just be checking whether it agrees with itself; label data is the
only independent check that actually means something for branded-shaped
ingredients. Several of the recipes deliberately carry the same
ingredient phrased two ways: a generic name ("tortilla chips") and a
specific one ("Mission tortilla chips"), so the benchmark checks both the
tool's default generic match and whether it correctly finds and prefers a
named product when the recipe asks for one by name.
Latest result (10 recipes, tool-equipped agent vs. bare-LLM-recall
agent, both scored against the same hand-verified label data, 2026-08-21):
the tool-equipped agent's mean absolute error across calories/protein/
carbs/fat was 4.99%, against 8.26% for the same agent with no
tool access. The tool wins outright on 7 of 10 recipes, decisively on
recipes with a genuinely hard branded ingredient or a meat cut whose fat
content is easy to misremember (chicken thigh, skirt steak). The three
recipes where bare recall did as well or better aren't evidence the tool's
own matching is weak. They're cases where the recipe itself left a
quantity uncountable (a garnish with no stated weight), forcing both
conditions to independently guess and adding noise unrelated to what the
benchmark is trying to measure. See note_on_TC10 in
tests/golden_recipes/eval_prompts.json for the one case worth fixing
before trusting its score. This number will drift as the fixture and the
tool both keep changing; treat it as the most recent reading, not a
permanent claim.
If you want to know | Read |
What the system must do, the confidence model, the macro report |
|
Module layout, data flow, testing strategy |
|
Exact tool signatures and data schemas |
|
What's built and what's left |
|
Rules for anyone (human or agent) working on this codebase |
|
Get verified macros (kcal, protein, carbs, fat) for one ingredient at one
quantity. fdc_id must come from a prior search_foods call -- never guess one.
amount accepts grams/kg, oz/lb, or a count phrase like "1 medium onion" (the
server resolves counts through a cited chain of real sources; it will raise
rather than guess if it cannot). label is the user's own word for this
ingredient, written verbatim -- do not paraphrase or clean it up, it is used to
judge how confident this match is. query should be a search string that
actually returns fdc_id among its results -- the server re-runs it and checks.
This catches an ID invented from memory; it does not confirm query is the
search you actually used, only that fdc_id is findable through it right now.
Open Food Facts fallback: set source to whatever
search_foods returned for the candidate you chose ("usda", the default, or
"off"). For "off", fdc_id holds the Open Food Facts barcode search_foods
already gave you, query is not consulted (no re-verification exists yet for
this source), and count-phrase quantities only resolve if the product itself
states a serving size -- otherwise give an explicit mass (grams/oz). The
response always carries a caveat naming this a crowdsourced, not USDA, source.
The response always includes a summary, a report_path, and totals (the
plate sum, computed server-side, even for one item and even with no target --
never add it up yourself). Read the summary in full and relay every flagged
item to the user, not just the confirmed ones -- a caveat you drop silently
(a low-confidence match, an assumed mass) defeats the only safety mechanism
this tool has. A macro genuinely absent from a food (no protein data at all,
for example) comes back as null with a caveat naming it, never as zero --
zero means the food truly has none.
The macros this tool returns are the only ones to state as fact for a food it matched -- never invent or estimate your own number in their place. The one narrow exception: if search_foods finds nothing at all for an item, you may estimate that single item's nutrition instead of leaving it out, but only if you say plainly it is your own guess, not verified data (C-28).
Pass target if the user has a kcal/protein/carb/fat goal for this lookup; use
the returned totals.outcomes, never compute whether a target was met yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| req | Yes | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and succeeds. It discloses query re-verification, server-side count resolution, 'raise rather than guess' behavior, server-computed totals, caveat-relay requirements, null-vs-zero macro semantics, and the rule against inventing numbers. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loaded with the core contract and organized by topic. Nearly every sentence carries safety-critical instruction, though some repetition around server-side computation and the 'never invent' rule could be tightened. Length is mostly justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description pre-defines the response shape (summary, report_path, totals), caveat handling, and failure modes (unresolvable counts, null macros, unverifiable queries, source caveats). It leaves no ambiguity about how to interpret results or handle edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates thoroughly. It explains fdc_id provenance, amount unit syntax and count phrases, label verbatim requirements, query verification, source values, and target usage. Every relevant input is given meaningful guidance beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states the exact operation: 'Get verified macros (kcal, protein, carbs, fat) for one ingredient at one quantity.' The singular 'one ingredient at one quantity' clearly distinguishes this from the batch sibling. It names the resource and the specific data returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says fdc_id must come from a prior search_foods call and never be guessed. It provides source-specific handling for 'off', a fallback policy when search_foods finds nothing, and clear conditions around count-phrase quantities. This gives explicit when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Same as get_nutrition, for multiple ingredients in one call -- use this instead
of calling get_nutrition in a loop, it is far faster to iterate on a recipe
with. One bad item does not fail the batch: a failed lookup comes back as a
marked failure alongside the successful ones, in the same order as reqs.
Read the whole summary before presenting results to the user: it names every
item that needed judgment, not just the ones that failed outright. Burying
three flagged items under eleven confirmed ones and only mentioning the
confirmed ones is the single most damaging way to misuse this tool. A macro
absent from one ingredient (no protein data at all, for example) comes back
null with a caveat naming it, not zero, and makes that macro's plate total
totals.macros come back null too -- reported as incomplete, not silently
summed as though the absent ingredient contributed nothing.
totals (the plate sum) is always computed server-side, whether or not you
pass target -- never add up the plate's macros yourself, even for a bare
"what does this plate total" question. Pass target once for the whole plate
to also get totals.outcomes, the per-macro met/not-met judgment; without
one, every macro's outcome reads "no target" and only the sum is judged.
| Name | Required | Description | Default |
|---|---|---|---|
| reqs | Yes | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: partial batch failures are returned alongside successful items, missing macros come back null with caveats and affect totals, and totals are always computed server-side so the agent must not sum itself. It also warns about the specific misuse of burying flagged items. These are significant behavioral traits beyond what any schema would convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place for a tool with complex failure and computation semantics. It is front-loaded with the core purpose and then systematically covers failure handling, summary reading, missing data, and totals. The structure is logical and the prose is dense without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the most critical aspects: failure handling, null handling, server-side totals, and target behavior. However, it does not specify the full response structure (e.g., exact fields of summary and totals beyond those mentioned) or any limits like pagination. Given there is no output schema, a bit more completeness would be ideal, but the core pitfalls are well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does explain the target parameter: passing it gives totals.outcomes, otherwise every macro reads 'no target'. However, it does not describe the structure of reqs beyond implying it is a list of ingredients, nor the fields within each NutritionRequest. The compensation is partial: target semantics are clarified, but reqs semantics are left to the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states this is the batch version of get_nutrition for multiple ingredients, and distinguishes it from the single-item sibling by advising to use it instead of a loop. The verb-resource pair (get nutrition for multiple ingredients) is specific and unambiguous, and it clearly separates from siblings like search_foods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: 'use this instead of calling get_nutrition in a loop' and explains the performance benefit. It also gives detailed operational instructions on reading the summary to avoid missing flagged items, and how to pass the target once for the whole plate to get outcomes, including the consequence of not passing it. This is abundant usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a saved recipe. Omit version for the latest. Macros are computed
fresh from the stored plate on every call, never cached -- if this ever
disagrees with something said earlier in the conversation, the plate or the
underlying food data changed since then; trust this call.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that macros are freshly computed and never cached, and clarifies that discrepancies should be resolved by trusting this call. This is valuable transparency about freshness and potential inconsistency, though it doesn't mention side effects (it's clearly a read) or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no superfluous words. The key instructions (purpose and version default) are front-loaded, and the freshness note is a necessary caveat. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only fetch tool with two parameters, the description is complete. It explains the version behavior and the freshness contract. It lacks explicit mention of not-found handling or return format, but the absence of an output schema keeps the burden lower. Given the simplicity, this is solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that omitting version returns the latest, which adds meaning beyond the schema's 'default: null'. It clarifies version's role as a selector for a specific version, and name is self-explanatory from the context. This goes beyond the schema's bare field definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb and resource: 'Fetch a saved recipe.' This distinguishes it from siblings like list_recipes (which lists all) and get_recipe_history (which retrieves past versions). The action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives version guidance but does not explicitly compare to alternatives. It implies use when you have a specific recipe name, but it never says 'use list_recipes to browse all recipes' or 'use get_recipe_history to see version history.' Missing explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch every saved version of a recipe, in order, to see how it evolved and
why -- each version's notes explains what changed. Use this before assuming
a recipe's current numbers are the only numbers it ever had.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that it fetches versions 'in order' and that each version's notes explain changes, which is useful behavioral info. However, it doesn't explicitly state read-only status, error behavior, or any side effects. For a fetch operation, this is reasonable but not exhaustive. Given no annotations, a score of 3 reflects adequate but not outstanding transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first states the action and purpose, the second gives usage guidance. No fluff, clearly front-loaded with the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one parameter, no nested objects), the description covers the essential behavior. It mentions the order and the notes field, and the output schema likely details the return structure. It doesn't address edge cases like a missing recipe, but for a simple fetch tool, that is minor. A score of 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage (no description for 'name'). The tool description does not explicitly describe what 'name' refers to, though the context implies it's the recipe name. The description provides no additional guidance on the parameter's format, meaning, or constraints. With no schema description, this is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch every saved version of a recipe'), the resource (recipe history), and the order ('in order' to see evolution). It explicitly distinguishes from get_recipe (which presumably returns the current state) by highlighting the historical perspective. The verb 'Fetch' is specific and the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context: 'Use this before assuming a recipe's current numbers are the only numbers it ever had.' This implies when to use it (when you need to see evolution) and when not to (when you only need current numbers). It doesn't explicitly mention alternatives, but the context implies get_recipe for current state. Slight deduction for not explicitly naming the alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved recipes, optionally filtered by protein range, calorie range, or whether a given fdc_id appears as an ingredient. Filters run against each recipe's current plate, computed fresh on read.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It goes beyond a simple list by revealing that filters are computed against each recipe's current plate and are fresh on read, which is meaningful behavioral context. It does not disclose sorting or pagination, but those are not essential for a list tool with an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the primary operation is front-loaded. The second sentence earns its place by clarifying freshness semantics that are not visible from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and an output schema exists, so return-value details are not required. The description covers the operation, filter semantics, optionality, and freshness. It stops short of perfect completeness by not stating whether multiple filters combine with AND, but this is a minor gap for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions, so the description must compensate. It does, by mapping 'protein range', 'calorie range', and 'fdc_id appears as an ingredient' to the schema's min_protein_g, max_kcal, and contains_fdc_id. This adds functional meaning beyond bare parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List saved recipes') and a clear resource, with optional filtering dimensions. It is distinguishable from siblings like get_recipe (single recipe) and search_foods (food database search) without needing to inspect schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended use clear: retrieving saved recipes with optional filters. It does not explicitly name alternatives or exclusions, but the context of siblings and the 'saved recipes' phrasing provides enough guidance for an agent to select it over single-recipe or food-search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently correct what a phrase means or what a count weighs, for this user. Use this the moment a lookup's summary flags something as wrong or low-confidence and the user tells you the right answer -- that correction is the entire point of reading the summary in the first place.
Pass fdc_id to fix which food a phrase resolves to, grams to fix what a
count weighs, or both. At least one is required. You cannot supply your own
description of the food: the server fetches the real USDA description and
writes that, so a bad correction is caught immediately rather than saved
blind.
When correcting grams, phrase must be the exact count phrase you would
pass as amount to get_nutrition (e.g. "1 medium onion"), not just the
ingredient's name (e.g. "onion") -- masses are looked up by that phrase,
and a mass saved under the wrong key is never found again.
Every future lookup of this phrase short-circuits to this correction at high
confidence. note should say why, briefly -- it is the only record of that
later.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| grams | No | ||
| fdc_id | No | ||
| phrase | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that the correction is permanent, that every future lookup short-circuits to it, that it is user-scoped, that the server fetches the real USDA description, and that the note is the only record of the correction's rationale. This is strong transparency about side effects and persistence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured: core action and trigger first, then parameter rules, then persistence behavior. Each sentence adds necessary information with no filler, and the most important usage guidance is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no annotations and no output schema, the description covers the tool's purpose, when to use it, what each parameter means, required constraints, and the lasting side effects. An agent has enough information to select and invoke the tool correctly without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters, and it does thoroughly: fdc_id fixes food resolution, grams fixes count mass, phrase must be the exact amount-style phrase used with get_nutrition, and note is the rationale. It even explains why the phrase exactness matters, which is critical for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('permanently correct'), a clear resource ('what a phrase means or what a count weighs'), and a scope ('for this user'). It also gives the triggering condition ('lookup's summary flags something as wrong or low-confidence'), which distinguishes it from siblings like get_nutrition, search_foods, and save_recipe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use the tool: when a lookup summary flags something wrong or low-confidence and the user provides the correct answer. It also gives important constraints, such as not supplying your own description and using the exact count phrase for grams. It does not explicitly contrast with alternative sibling tools, but the intended usage context is unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a new version of a recipe. plate is the user's own plate only, in
absolute grams per ingredient -- never a household total. Each ingredient
needs an fdc_id from a real lookup (never invent one) and its exact amount in
grams. shares records everyone else at the table as a fraction of the user's
plate (e.g. {"maria": 0.75}) -- leave it empty if cooking just for the user,
that is the common case, not a special one.
Saves are append-only: this always creates a new version, it never overwrites
one. notes is required and should say what changed and why (e.g. "corrected
cooked weight after weighing it") -- it is the only record of that later, and
the most useful field in the whole store.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| notes | Yes | ||
| plate | Yes | ||
| shares | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It explicitly reveals append-only semantics ('always creates a new version, never overwrites'), notes as the only record of changes, and the requirement that fdc_id be real. This is far beyond what the schema provides and gives the agent essential non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then systematically explains each parameter with examples. It is dense with useful guidance and contains minimal filler, though the phrase 'the most useful field in the whole store' is somewhat editorial. Overall it is well-structured and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested objects and no output schema, the description covers all input semantics, the append-only behavior, and the notes requirement, which is enough to invoke it correctly. It does not describe the return value or error handling, but those are less critical for a save operation. The guardrail about fdc_id is a sufficient warning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It thoroughly explains plate (absolute grams per ingredient, not household total), shares (fractions of user's plate, leave empty for solo cooking), and notes (required, should describe changes). It also clarifies fdc_id must come from a real lookup. Only 'name' is left implicit, but its meaning is self-evident.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Save a new version of a recipe', a specific verb and resource. It further distinguishes itself from overwriting by stating 'it never overwrites one', which clarifies its role relative to siblings like save_override. The purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on how to use the tool correctly: plate must be the user's own portion, shares is for others and should be empty when cooking alone, and fdc_id must come from a real lookup. It states 'Saves are append-only: this always creates a new version, it never overwrites one', which is an explicit when-not scenario, but it does not name an alternative tool for overwriting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search USDA FoodData Central for candidate foods matching a plain-language query (e.g. "chicken breast", "greek yogurt"). Returns ranked candidates: generic (Foundation, SR Legacy) before branded, always. Raises only if nothing at all matches -- never returns an empty list.
This is the ONLY way to find a valid fdc_id. Never invent, recall, or reuse an
fdc_id from memory or an earlier conversation: call this tool first, read the
returned descriptions, and choose the one that actually matches what the user
meant. Pass this exact query string as query to get_nutrition or
get_nutrition_batch so the server can verify your chosen fdc_id was really one
of these results. Each candidate carries a source field ("usda" or "off") --
pass it through as NutritionRequest.source unchanged; fdc_id itself always
goes in the same field either way.
A returned candidate can still fail to fetch (USDA's own search index can be ahead of its detail records, especially for newer Foundation entries) -- if get_nutrition/get_nutrition_batch reports that id as failed, do not give up: try the next candidate from this same list. A failed fetch on its own is not evidence the food itself doesn't exist.
Open Food Facts fallback: set expect_branded=True when
the ingredient names or clearly implies a specific commercial product (a
brand name, "Mission Carb Balance," "Nature's Own keto bun," or a stated
attribute like "low-carb"/"keto" you suspect USDA does not carry under that
name) -- the same judgment X-7 already asks you to make about when to search
using a stated attribute, extended one step further. When set, this also
searches Open Food Facts (a free, crowdsourced, barcode-indexed database)
and reserves a slice of limit for any candidate that passes a real
plausibility gate (no impossible or self-contradictory nutrition values) --
still fundamentally less trustworthy than a USDA record, anyone can edit an
entry, and get_nutrition always attaches a caveat naming this plainly.
Leave it False (the default) for a plainly generic ingredient (eggs, potato,
olive oil, chicken breast) -- Open Food Facts is a packaged-goods database
and has nothing to offer a commodity food, so trying it there is pure
latency with no upside. USDA alone is still searched every time regardless
of this flag, and Open Food Facts is still tried as a last resort if USDA
returns literally nothing even when this flag is False, so a real zero-
result case is never silently unhandled just because you forgot to set it.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| expect_branded | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses ranking order, exception behavior, potential fetch failures, source trustworthiness, Open Food Facts caveats, and the always-tried USDA fallback, leaving little ambiguity about tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized and front-loaded with purpose and usage, but it is somewhat verbose and repeats fallback and trust caveats in multiple places. It remains valuable and focused, though trimming redundant sentences would improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the lack of parameter descriptions in the schema, the description covers all essential operational aspects: matching, ranking, error behavior, source selection, failure retry guidance, and fallback logic. The mention of the output schema means return-value explanation is unnecessary, and the description still clarifies key response characteristics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though the schema provides only names and defaults, the description richly explains all three parameters: query should be the exact string passed through, limit reserves slices for candidates, and expect_branded has nuanced semantics for when to enable Open Food Facts. This far exceeds what the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a USDA FoodData Central search for candidate foods matching a plain-language query, with a specific verb and resource. It also distinguishes this search tool from nutrition lookup and recipe siblings by stating it returns ranked candidates and raises only when nothing matches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states this is the only way to obtain a valid fdc_id and instructs the agent to call it before any nutrition lookup. It also gives detailed when-to/when-not-to guidance for the expect_branded flag, including fallback behavior when USDA returns nothing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_nutritionget_nutrition_batchget_recipeget_recipe_historylist_recipessave_overridesave_recipesearch_foodsScored across 8 tools
Each tool has a clearly distinct role: search_foods discovers candidate ingredients, get_nutrition and get_nutrition_batch retrieve verified nutrition data for one or many ingredients, save_override permanently corrects lookup data, and save_recipe/get_recipe/get_recipe_history/list_recipes manage the lifecycle of saved recipes. The boundary between fetching a food and fetching nutrition, or between correcting a lookup and saving a full recipe, is strongly reinforced by detailed descriptions.
Most tools follow verb_noun (search_foods, get_nutrition, save_recipe, list_recipes). Minor deviations: save_override is verb_verb rather than verb_noun, and get_nutrition_batch is a noun modifier rather than verb_noun. Mixed conventions, plus the label get_nutrition_batch when save/retrieve/recipes, however, are predictable and readable, so the set remains usable.
8 tools are correctly calibrated for a nutritional dataset and recipe store: 2 ingredient retrieval tools, batch mode, correction, recipe storage, and versioning. Each of the 8 tools is clearly justified and applicable, and complete omission is saved in the moderation of a useful compact-size dataset.
The core workflow is well covered: find ingredient, get nutritional info, batch retrieval, correct with override, save and read recipes, history and listing. The missing note is delete_recipe; save_recipe remains an append-only operation (each save creates a new version) with no way to remove old recipes. Which is a real limitation—a user can add recipes but cannot delete them. The current scope may be intentional, but this omission prevents entire recipe lifecycle management.
Natural-language calorie lookup. Send '2 large eggs', get USDA-sourced nutrition data.
Food and nutrition data: search, macros, and comparisons
USDA FoodData Central nutrition data: search foods, compare macros, and analyze meals.
Resolve Japanese food names to nutrition facts. All 2,538 foods from Japan's official tables.