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., "@foodos-mcp Scale my chicken recipe to 6 portions with different serving sizes and give macros per portion."
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.
Turn recipes into traceable nutrition numbers, cooked-weight calculations, and portions that fit each eater — all through the Model Context Protocol (MCP).
Your AI assistant handles the conversation. foodos-mcp handles the math. 🧮
LLMs can help you find dinner, but they can also guess gram weights, invent macros, or split a batch in half when everyone needs a different portion. This server makes those calculations deterministic and auditable, from the first ingredient to the last lunchbox.
🔎 Know where every number came from. Macro values trace to a USDA food ID, an Open Food Facts barcode, or data you supplied.
⚖️ Weigh it cooked. Count it correctly. Turn raw ingredient totals into macros per 100 g of the finished batch.
🍛 One batch, different portions. Size a serving by a target, a fixed weight, or whatever is left.
📦 Give leftovers a plan. Keep track of portions for tonight and boxes for later.
🛑 Keep guesses off the plate. Ambiguous food lookups return candidates for you to choose from.
🥕 Raw ingredients → 🧮 Batch macros → 🍳 Cooked weight
↓
Macros per 100 g cooked
↓
🍽️ Portions sized for each eater
↓
📦 Leftovers & meal prepOne eater needs enough protein to finish their daily target. Another takes 180 g off the scale. A third takes what is left. Tuesday's lunch gets a box, too. Equal portions are optional. Getting the math right is the whole point. 🙌
🚀 Get started · 🍗 See the math · 🧰 Explore the tools · 🛠️ Contribute
Related MCP server: nutrition-mcp-server
npx foodos-mcp # stdio, for a local client
npx foodos-mcp --transport http --port 3000Node 22.12 or newer. You need a free USDA API key, which takes about a minute to get at api.data.gov/signup.
Add this to claude_desktop_config.json, then restart Claude Desktop.
{
"mcpServers": {
"foodos": {
"command": "npx",
"args": ["-y", "foodos-mcp"],
"env": {
"FDC_API_KEY": "your-key-here",
"FOODOS_CONTACT": "you@example.com"
}
}
}
}FOODOS_CONTACT goes in the User-Agent when the server reads Open Food Facts, which their terms ask for. Everything works without it; you are just anonymous.
Let’s roast 800 g of chicken and follow the numbers all the way to the plate. Every step is checkable. 🔍
1. 🔎 Find the food. searchFood with "chicken breast raw" returns candidates from USDA. Pick one; the model should show you the list rather than choose. Here it is fdcId 2646170, "Chicken, breast, boneless, skinless, raw".
2. 🧬 Get its macros. getFoodMacros returns, per 100 g:
per 100 g | |
Protein | 22.525 g |
Fat | 1.934 g |
Carbohydrate | 0 g |
Energy | 106.034 kcal |
It also reports energySource: "atwater_general_2047". Foundation foods carry no plain energy nutrient at all, only the two Atwater values, and the server tells you which one it used rather than leaving you to wonder.
3. 🧮 Total the batch. computeBatchMacros with 800 g of it: 180.2 g protein, 15.5 g fat, 848 kcal.
4. 🍳 Weigh it after cooking. You roast it and the tray comes out at 600 g. setCookedYield with rawG: 800, cookedG: 600 gives a yield factor of 0.75 and, per 100 g cooked: 30 g protein, 2.6 g fat, 141 kcal.
5. 🍽️ Serve it up. portionBatch with two rules, one fixed weight and one remainder:
Eater | Rule | Weight | Protein | Energy |
A | fixed 180 g | 180 g | 54.1 g | 254 kcal |
B | remainder | 420 g | 126.1 g | 594 kcal |
54.06 plus 126.14 is 180.2, which is the batch. The arithmetic runs at full precision from end to end and only the presentation is rounded, so the reconciliation is exact even where two rounded figures are each a tenth off.
🎯 Want a portion that fills a target? Change A's rule to solveForRemaining and give A a daily protein target of 150 g with 100 g already eaten. A gets the 166 g that carries the remaining 50 g of protein, and the response says bindingConstraint: "proteinG" along with where fat and energy landed. If that portion blows A's fat target, the response says so in the residuals rather than leaving you to notice.
🏃 Try it yourself: examples/worked-example.ts runs this against the live API with your own key.
📖 Read a recipe. parseRecipe pulls the schema.org data a page publishes for machines. parseIngredientLine splits one line into its parts and flags what is ambiguous, so "1 medium onion" comes back as a size descriptor rather than as 150 g.
🔎 Look up nutrition. searchFood, getFoodMacros, lookupBarcode, toGrams.
🧮 Calculate the batch. computeBatchMacros, setCookedYield.
🍽️ Portion your plates. portionBatch, the reason this repository exists.
🛒 Plan the next batch. planBatchSize, scaleRecipe, shoppingList.
📚 Peek under the hood. foodos://yield-factors and foodos://densities expose the bundled tables so you can see exactly what a calculation was based on. foodos://rate-limit-status shows how much of the hourly budget is left.
💬 Follow the guided workflow. portionABatch walks a client through the whole chain, from a URL to portions on plates.
Here’s where the data comes from, along with the licensing and caching considerations behind the integrations.
Source | Verdict | Why |
USDA FoodData Central | Primary nutrition source | US public domain under CC0 1.0. Free key from api.data.gov. No caching restriction, so this server caches aggressively. |
Open Food Facts | Secondary, for packaged goods and barcodes | Open data under the ODbL, contents under the DbCL. Their terms ask for a descriptive User-Agent with a contact address, which this server sends. |
Spoonacular | Not integrated | Their terms cap caching at about an hour and then require deletion. That is incompatible with a local store, and a local store is what makes the rate limit survivable. |
Edamam | Not integrated | Their terms prohibit automated programmatic requests intended to collect or save data. An MCP server is exactly that. |
Cooking yields come from the USDA Table of Cooking Yields for Meat and Poultry, Release 2 (CC0), plus rows transcribed by hand from Agriculture Handbook 102 (1975, public domain) for rice, pasta, lentils and oats, each citing its page. Densities are derived from the USDA SR Legacy bulk export, a 6 MB public-domain download that needs no API key, with each row citing the food and portion it came from. A cup of flour is 125 g and a cup of honey is 339 g, which is why volume never converts to weight without knowing the ingredient.
Rice roughly triples in weight when cooked and lentils nearly do. A yield factor is not always below 1, and treating it as though it were would be wrong for half a kitchen.
FoodData Central runs behind api.data.gov: 1,000 requests an hour per key, on a rolling window, with a 429 when you go over. A single recipe with fifteen ingredients can burn thirty calls between searching and looking up, so this is a real ceiling rather than a theoretical one.
Here’s how the server keeps the budget visible:
A local counter refuses the call before it leaves the process when the budget is spent, and tells you when it frees up.
Response headers are authoritative. If USDA says 40 requests remain, the local count is corrected to match, because a key shared with another client is further along than this process can know.
The default budget is 800, deliberately under the real 1,000, so a second client does not push you into a 429.
Nothing queues, sleeps or retries. Only you know whether the rest of the work is worth what is left.
Cache hits never count. Lookups are cached for a month, which is allowed without reservation because the data are public domain.
Check foodos://rate-limit-status before a big batch. Set FDC_HOURLY_BUDGET to change the ceiling.
The real answer, when this becomes a problem, is that USDA publishes complete monthly exports of about 6 GiB. A local copy takes the API out of the hot path entirely. That is the v0.2 plan; there is a TODO(bulk-import) in the client pointing at it.
DEMO_KEY works for a first smoke test and is capped at ten requests an hour, which you will hit almost immediately. It is never used as a fallback in code.
Variable | Default | What it does |
| none | Required for anything that reads USDA data. No default key ships in this repository. |
|
| Requests an hour before the server refuses to make more. |
| repository URL | Contact address sent in the User-Agent, as Open Food Facts asks. |
| platform cache directory | Where cached lookups live. |
|
|
|
foodos-mcp --transport http --host 127.0.0.1 --port 3000 --allowed-hosts foodos.example.comThe endpoint is POST /mcp, and GET /healthz answers for a load balancer. It runs stateless, so there is no session affinity to arrange.
There is no authentication in this server, on purpose. Terminate TLS and auth at the reverse proxy and keep the server bound to loopback:
location /mcp {
proxy_pass http://127.0.0.1:3000/mcp;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Connection "";
proxy_buffering off; # streamable HTTP sends server-sent events
proxy_read_timeout 300s;
}Passing --allowed-hosts turns on DNS rebinding protection for the hosts you name.
foodos-mcp focuses on recipe and portion calculations. It provides numbers, with no health advice, diet recommendations, or judgments about your plate.
There are no accounts or built-in authentication. The server reads two public food data sources, caches lookups locally, and does the arithmetic.
pnpm install
pnpm check # biome, tsc and vitest
pnpm test:coverage
pnpm buildThe test suite runs entirely offline. Every HTTP request is intercepted, and an unhandled one fails the run, so a forgotten network call cannot reach USDA from CI.
Ready to dig in? Read CONTRIBUTING.md before opening a pull request. 🧑🍳
MIT licensed. Fork it, explore it, and build something delicious. See LICENSE.
USDA FoodData Central data are in the public domain. U.S. Department of Agriculture, Agricultural Research Service. FoodData Central, fdc.nal.usda.gov. Open Food Facts data are available under the Open Database License.
Total the macros of a whole batch from its ingredients. Each ingredient needs a nutrition source and a weight. Any ingredient missing either is returned in unresolved with candidate matches and is never dropped or approximated: the totals then carry isComplete false and are a partial sum.
| Name | Required | Description | Default |
|---|---|---|---|
| ingredients | Yes | ||
| suggestCandidates | No | Defaults to true. Costs one food search per unresolved ingredient. |
| Name | Required | Description |
|---|---|---|
| budget | Yes | |
| totals | Yes | A partial sum when isComplete is false. Unresolved items are never dropped. |
| coverage | Yes | Lets the caller tell a missing pinch of salt from a missing 500 g of meat. |
| warnings | Yes | |
| totalRawG | Yes | Sum of the resolved ingredient weights only. |
| isComplete | Yes | |
| unresolved | Yes | |
| ingredients | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/idempotent annotations, the description adds valuable behavior: unresolved ingredients are returned with candidate matches, totals are partial with isComplete false, and results are never dropped or approximated. This meaningfully enriches what the annotations alone 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?
Three tight sentences: the first states the core purpose, and the next two pack essential caveats about unresolved ingredients and partial totals. There is no filler or repetition of schema details.
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 a detailed input schema, an output schema, and safety annotations, the description covers the key invocation semantics: prerequisites, unresolved handling, and partial-sum behavior. It does not discuss candidate-search cost or suggestCandidates, but the schema already documents those, so the remaining gap is primarily the implicit sibling-tool guidance.
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 maps the core semantics of ingredients to 'nutrition source' and 'weight', and explains the consequence of missing either. With only 50% schema description coverage, this is useful added meaning, though it leaves suggestCandidates and the quantity/unit interplay to the 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 description opens with a precise verb and resource: 'Total the macros of a whole batch from its ingredients.' It clearly scopes the tool to batch-level aggregation, distinguishing it from single-food tools like getFoodMacros and from planning/portioning tools like portionBatch or planBatchSize.
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 gives clear preconditions: each ingredient needs a nutrition source and a weight, and unresolved ingredients are never dropped or approximated. However, it does not explicitly state when to choose this tool over siblings such as getFoodMacros or parseIngredientLine, nor does it name any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-100 g macros for one USDA food id, with its portion weights. Also reports which energy nutrient was used, since Foundation foods report Atwater factors rather than a plain energy value.
| Name | Required | Description | Default |
|---|---|---|---|
| fdcId | Yes |
| Name | Required | Description |
|---|---|---|
| fdcId | Yes | |
| budget | Yes | |
| per100g | Yes | |
| dataType | Yes | |
| portions | Yes | |
| fromCache | Yes | |
| description | Yes | |
| energySource | Yes | |
| foodCategory | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral nuance: Foundation foods report Atwater factors rather than a plain energy value, and the tool reports which energy nutrient was used. This goes beyond what annotations or the schema alone 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?
Two sentences with no filler. The main function is front-loaded, and the second sentence adds a relevant edge case without bloating the description. Every sentence earns its place.
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 single-parameter, read-only tool with a rich output schema and strong annotations, the description is nearly complete. It covers output content, portion weights, and an important energy-value nuance. The only missing piece is guidance on where fdcId comes from or when to prefer a sibling tool, but that is not critical for invoking it correctly.
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?
With schema description coverage at 0%, the description carries the full burden, but it only says 'USDA food id.' The schema already shows fdcId is a positive integer, so the description adds little beyond restating the property name. It does not explain how to obtain a valid fdcId or connect it to searchFood.
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 tool returns per-100 g macros for one USDA food id, plus portion weights. It is specific about scope ('one USDA food id') and output, which separates it from batch tools like computeBatchMacros. However, it never explicitly names a sibling or contrast, so it falls just short of full differentiation.
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?
Usage is implied: call this when you need macros for a single USDA food id. There is no explicit when-to-use, when-not-to-use, or alternative routing despite siblings like searchFood, lookupBarcode, and computeBatchMacros existing. The context is clear enough, but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-100 g macros for a packaged product from Open Food Facts. Community-contributed label transcriptions, so confidence is medium rather than high.
| Name | Required | Description | Default |
|---|---|---|---|
| barcode | Yes |
| Name | Required | Description |
|---|---|---|
| brands | Yes | |
| barcode | Yes | |
| per100g | Yes | |
| fromCache | Yes | |
| productName | Yes | |
| nutritionDataPer | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context by stating that data is community-contributed and confidence is medium, which helps the agent calibrate trust in the result. No contradiction with annotations.
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, front-loaded with the main purpose and source, followed by a meaningful data-quality caveat. There is no filler or repetition of schema details.
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 simple one-parameter lookup with an output schema and strong annotations, the description covers the input context, return granularity, and trustworthiness. The main missing piece is explicit guidance on how this tool relates to sibling lookup tools, but the rest of the context is adequately supplied.
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 carries some burden for explaining the parameter. It adds context by linking the barcode to packaged products and Open Food Facts, but it does not elaborate on barcode format or example values. The schema's pattern and property name already provide the basic validation semantics.
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 what the tool returns — per-100g macros for a packaged product from Open Food Facts — and the name plus barcode schema identify the lookup mechanism. It does not explicitly distinguish this from the sibling getFoodMacros, so it misses some sibling differentiation, but the core purpose 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 implies when to use it: when you need per-100g macros for a packaged product identified by barcode. It also alerts the agent to data-quality limitations. However, it gives no explicit guidance about when not to use it or how it compares to alternatives like getFoodMacros or searchFood.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Split one ingredient line into quantity, unit, ingredient and preparation note. Reports what is ambiguous instead of resolving it: '1 medium onion' comes back flagged as a size descriptor, never as a weight in grams.
| Name | Required | Description | Default |
|---|---|---|---|
| line | Yes |
| Name | Required | Description |
|---|---|---|
| raw | Yes | |
| name | Yes | |
| unit | Yes | Normalized unit id such as 'tablespoon'. Null for bare counts. |
| unitRaw | Yes | |
| quantity | Yes | |
| confidence | Yes | |
| ambiguities | Yes | |
| preparation | Yes | Text after the first comma, such as 'diced'. |
| quantityMax | Yes | Upper bound when the line gives a range. |
| isGroupHeader | Yes | |
| sizeDescriptor | Yes | Words like 'medium' or 'large'. Reported, never converted to grams. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by disclosing a key behavioral trait: it reports ambiguity rather than resolving it, with a concrete example ('1 medium onion' flagged as a size descriptor). This is exactly the kind of contextual behavioral detail that helps an agent anticipate tool output, especially with readOnly and idempotent hints already present.
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 sentences, front-loaded with the primary function and followed by a helpful behavioral example. There is no filler or redundant repetition of the tool name.
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 output schema covers return structure, annotations cover harmlessness and idempotency, and the description covers the important ambiguity-handling nuance. For a single-parameter parser with rich surrounding structured data, nothing necessary for correct invocation is missing.
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 carries the weight. It explains that the 'line' parameter is an ingredient line and illustrates the expected structure via the example and output categories. It does not specify formatting rules or edge cases, but with only one simple string parameter, this is a strong compensation.
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 verb 'Split' and the resource, 'one ingredient line', and enumerates the output categories: quantity, unit, ingredient, and preparation note. It also distinguishes itself from siblings by focusing on a single line, unlike parseRecipe, and defines its parsing scope explicitly.
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 it clear that this tool operates on a single ingredient line, which implies when it should be used. However, it does not explicitly state when not to use it, mention parseRecipe as the alternative for multi-line/recipe input, or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a recipe from a web page. Returns its title, ingredient lines as written, declared servings and instructions, taken from the schema.org data the page publishes for machines. Fails clearly when a page has no structured data rather than guessing at the markup.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public http(s) URL of a recipe page. |
| Name | Required | Description |
|---|---|---|
| title | Yes | |
| author | Yes | |
| finalUrl | Yes | |
| fromCache | Yes | |
| sourceUrl | Yes | |
| instructions | Yes | |
| ingredientLines | Yes | |
| declaredServings | Yes | The first integer found in the page's recipeYield, or null. This is the author's claim about servings, not a measured household portion, and is never guessed. |
| extractionMethod | Yes | |
| declaredYieldText | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description reveals that data comes specifically from schema.org structured data and that the tool fails clearly rather than guessing when no structured data exists. This is valuable behavioral context that annotations alone do not provide.
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 compact, front-loaded with the core action, and every sentence earns its place. It covers what the tool does, what it returns, and its failure behavior without redundancy.
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 single-parameter tool with an output schema, the description is complete: it specifies the input, the source of the data, the returned fields, and the failure mode. No additional guidance is needed for correct invocation.
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 schema already covers the single url parameter at 100% with a clear description and format. The tool description reinforces that it should be a public recipe web page, but does not add significant meaning beyond the schema, so it meets the baseline.
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 names a specific verb and resource: reading/parsing a recipe from a web page. It also specifies exactly what is returned (title, ingredient lines, servings, instructions), which distinguishes it clearly from siblings like parseIngredientLine.
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: use this when you have a recipe URL and need machine-readable structured data from the page. It does not name alternatives or explicitly state when not to use it, but the context is strong enough to guide selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Work out how much to cook, from an explicit list of who is eating and how much each takes. Size slots by weight or by macros where you can. Sizing a slot as a count of the recipe's declared servings always warns, because 'serves 4' is the author's claim about their own portions and not a measurement of a household meal. Returns the arithmetic so it can be checked.
| Name | Required | Description | Default |
|---|---|---|---|
| basis | Yes | ||
| slots | Yes | ||
| allowIncomplete | No | Permit macro-sized slots against totals whose confidence is 'unresolved'. |
| Name | Required | Description |
|---|---|---|
| slots | Yes | |
| totals | Yes | |
| warnings | Yes | |
| arithmetic | Yes | |
| perDeclaredServing | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond that: sizing by declaredServings 'always warns', and the result includes arithmetic for verification. This helps the agent anticipate output behavior and understand why warnings may appear. No contradiction with annotations.
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?
Four sentences with no filler: the purpose is front-loaded, the sizing guidance is concise, the warning is explicit, and the return behavior is stated. Every sentence contributes to the agent's understanding. This is appropriately sized for the tool's complexity.
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 nested schema and the presence of an output schema, the description covers the essential decision points: what input is needed (explicit eater list and slot sizes), which sizing methods are preferred, what to avoid (declaredServings), and what the return contains. It does not explain the interaction between basis fields and slot sizing, which a complex tool might warrant, but it is mostly complete for correct invocation.
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 33%, so the description carries extra responsibility. It does clarify the meaning of the 'slots' size variants (weight, macros, declaredServings) and explains why declaredServings is discouraged. However, it does not explain the 'basis' object's fields like totalRawG, yieldFactor, or totalCookedG, nor does it address allowIncomplete. It adds some semantic value but does not fully compensate for the low schema coverage.
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 exactly what the tool does with a specific verb ('work out how much to cook') and resource (batch size from an explicit eater list). It differentiates from siblings by emphasizing the explicit list and individual slot amounts, and by explicitly contrasting with declared-servings-based sizing. An agent can distinguish it from scaleRecipe or computeBatchMacros without opening the schema.
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 clearly indicates when to use it: when you have an explicit list of who is eating and how much each takes. It also gives a concrete usage rule ('Size slots by weight or by macros where you can') and warns against using declared servings. It does not explicitly name sibling alternatives or provide exclusion criteria, so it misses the top tier, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Split a cooked batch into portions that are sized per eater rather than divided equally. Each portion carries its own rule: solve for what an eater still needs today, take a fixed weight, hit a macro target, take the remainder, or set food aside for later. Returns each portion's weight and macros, which constraint decided the weight, and where the other targets landed. Asking for more than the batch holds is an error, never a silent scale-down. Weights are rounded to the gram for reporting, so adding up the portions can differ from the batch by a gram; allocatedG and leftoverG carry the exact figures.
| Name | Required | Description | Default |
|---|---|---|---|
| eaters | No | Required for solveForRemaining. When given, every portion also reports how it lands against that eater's remaining targets. | |
| portions | Yes | ||
| cookedBasis | No | Defaults to measured. 'estimated' means the cooked weight came from a yield table, which caps the confidence of every portion at medium. | |
| totalMacros | Yes | Macros of the whole cooked batch. | |
| totalCookedG | Yes |
| Name | Required | Description |
|---|---|---|
| byEater | Yes | |
| portions | Yes | |
| warnings | Yes | |
| leftoverG | Yes | Zero whenever one of the rules is 'remainder'. |
| allocatedG | Yes | |
| per100gCooked | Yes | |
| leftoverMacros | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the core safety profile is covered. The description adds valuable behavioral context beyond those: over-allocation is an error rather than a silent scale-down, and weights are rounded for reporting with exact figures carried in allocatedG and leftoverG. This is useful transparency that the annotations do not 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 a single focused paragraph with no filler. The main purpose is front-loaded, followed by the rule types and then the two critical behavioral caveats. Every sentence earns its place, and the length is appropriate for the complexity of the tool.
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 complexity of the input schema and the fact that an output schema exists, the description is reasonably complete. It covers the portioning rules, return contents, error handling, and rounding behavior. It does not mention any prerequisites or data-flow dependencies (e.g., computeBatchMacros feeding this tool), but those are not essential for correct invocation.
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?
With schema description coverage at 60%, the description compensates well for the least obvious parameter, the `rule` field, by explaining the five modes (solve for remaining, fixed weight, macro target, remainder, reserve). It also clarifies that each portion is independently sized. It does not deeply elaborate on totalMacros or totalCookedG, but those are self-explanatory from the 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 description states a specific verb and resource: 'Split a cooked batch into portions' and immediately contrasts it with equal division. It enumerates the five portioning rules, making its function unambiguous and clearly distinct from siblings like computeBatchMacros or planBatchSize.
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 implies when to use the tool (when you need per-eater portioning with individual rules) but never explicitly names alternatives or conditions for choosing another tool. It does not provide when-not-to-use guidance, so an agent must infer the boundary from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scale a raw ingredient list. Scaling to a macro target needs the recipe's current totals, from computeBatchMacros: this server does not infer what a recipe contains. Amounts in discrete units such as eggs are reported when they land on a fraction, never rounded here.
| Name | Required | Description | Default |
|---|---|---|---|
| by | Yes | ||
| ingredients | Yes |
| Name | Required | Description |
|---|---|---|
| factor | Yes | |
| warnings | Yes | |
| arithmetic | Yes | |
| ingredients | Yes | |
| scaledTotals | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the bar for additional disclosure is lower. The description adds two important non-obvious behaviors: macro-target scaling requires precomputed current totals because the server does not infer them, and discrete-unit amounts are reported as fractions rather than rounded. These are directly useful for predicting 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 three sentences with no filler. The first sentence states the purpose, and each subsequent sentence adds a distinct, valuable caveat: the prerequisite for macro scaling and the rounding behavior for discrete units.
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 rich input schema and existing output schema, the description covers the most critical non-obvious constraints: needing current totals from computeBatchMacros and never rounding discrete units. It does not enumerate the three scaling modes, but the schema fully specifies them, so an agent has enough context to invoke the tool correctly.
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%, and the description does not compensate by explaining the `by` parameter's three allowed kinds or the `ingredients` array structure. It only mentions 'raw ingredient list' and 'current totals,' which are already present in the schema, so it adds minimal parameter meaning beyond what structured fields provide.
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 uses a specific verb and resource: 'Scale a raw ingredient list.' It clearly names the tool's core action and even calls out the macro-target mode, but it does not explicitly distinguish itself from sibling scaling tools like portionBatch or planBatchSize.
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 useful contextual guidance for macro-target scaling by pointing to computeBatchMacros and warning that the server does not infer recipe contents. However, it does not explain when to use factor or targetServings modes, nor does it contrast the tool with sibling scaling alternatives like portionBatch or planBatchSize.
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 a food. Prefer Foundation and SR Legacy results for whole ingredients: they are laboratory-analysed and carry portion weights. Use Branded only for packaged products. Show the user the candidates and let them choose; do not pick silently.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Defaults to 10. | |
| query | Yes | ||
| dataType | No | Defaults to ['Foundation','SR Legacy']. Prefer those two for whole ingredients: they are laboratory-analysed and carry portion weights. Use 'Branded' only for packaged products. |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| budget | Yes | |
| fromCache | Yes | |
| totalHits | Yes | |
| candidates | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly, openWorld, and idempotent annotations, the description discloses non-obvious behavioral expectations such as surfacing candidates for user choice, not silently selecting, and why Foundation/SR Legacy are preferred. This is meaningful extra context that annotations alone would not 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?
Three compact sentences, with the core action front-loaded and every sentence earning its place. No filler or duplicate structured information beyond what is helpful context.
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 output schema exists and readOnly, openWorld, and idempotent annotations are already available, the description covers the key behavioral rule and data-source rationale. It does not mention alternative sibling routing, but the tool is simple and the necessary usage context is complete enough for an agent to invoke it correctly.
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 schema already documents limit and dataType, including defaults and data-type preferences, while the description adds only marginally to query semantics. The description restates dataType guidance rather than adding new parameter meaning, so it is adequate but not highly informative beyond the 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 description states a specific action on a clear resource: "Search USDA FoodData Central for a food", and distinguishes itself by explaining the role of each data source, which separates it from sibling tools like lookupBarcode or getFoodMacros. The scope is immediately recognizable to an agent, with additional selection guidance that further clarifies what kind of results this tool surfaces.
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 gives explicit when-to-use guidance for Foundation/SR Legacy versus Branded results and adds a clear interaction duty: show candidates to the user and do not pick silently. It does not explicitly name sibling alternatives, but the data-source conditions are clear enough to route typical food-search use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert batch totals into per-100 g cooked values. Pass the measured cooked weight when you have it. Failing that, pass a yield factor you measured yourself, or a yieldHint to look one up in the bundled USDA tables. A hint matching several rows returns unresolved with candidates rather than choosing one. Note that rice and dried legumes gain weight: their yield factors are above 1.
| Name | Required | Description | Default |
|---|---|---|---|
| rawG | Yes | ||
| cookedG | No | Measured cooked weight. Wins over everything else. | |
| yieldHint | No | Look a factor up in the bundled USDA tables. Used only when neither cookedG nor yieldFactor is given, and only when exactly one row matches. | |
| totalMacros | Yes | ||
| yieldFactor | No | Your own measured factor. Second choice. |
| Name | Required | Description |
|---|---|---|
| rawG | Yes | |
| basis | Yes | |
| status | Yes | |
| cookedG | Yes | |
| warnings | Yes | |
| yieldRow | Yes | |
| arithmetic | Yes | |
| candidates | Yes | |
| yieldFactor | Yes | |
| per100gCooked | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. The description adds valuable non-obvious behavior: ambiguous yield hints return unresolved with candidates rather than auto-selecting, and rice/dried legumes have yield factors above 1. No contradiction with annotations.
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?
Four concise sentences with no filler. The purpose is front-loaded, and each sentence carries operational information: what the tool does, input precedence, ambiguity behavior, and a domain caveat.
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?
Covers purpose, parameter precedence, ambiguity handling, and a useful real-world caveat. An output schema exists, so return-value details are handled elsewhere; the only minor gap is lack of direct sibling differentiation.
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 60%, and the description compensates by explaining the meaning and precedence of cookedG, yieldFactor, and yieldHint, including when yieldHint is used. rawG and totalMacros are not deeply described, but their roles are inferable from the phrase 'batch totals' and the schema structure.
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?
Description states a specific operation: 'Convert batch totals into per-100 g cooked values', and identifies the key inputs (cooked weight, yield factor, yield hint). It is clear and distinct from the sibling list, though it does not explicitly name a sibling alternative.
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?
Provides an explicit precedence chain: cookedG first, then yieldFactor, then yieldHint, and notes the ambiguity behavior for multi-row hints. It gives clear context for how to choose inputs, though it does not contrast with related tools like portionBatch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate raw quantities across recipes, grouped by USDA food category, with what you have on hand subtracted. Two ingredients merge only when they resolve to the same food.
| Name | Required | Description | Default |
|---|---|---|---|
| onHand | No | ||
| recipes | Yes |
| Name | Required | Description |
|---|---|---|
| budget | Yes | |
| groups | Yes | |
| warnings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, and idempotentHint, covering safety and idempotency. The description adds valuable behavioral context: the rule that ingredients merge only when they resolve to the same food, and that on-hand quantities are subtracted. This goes beyond the annotations and helps the agent predict 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 two sentences with no extraneous words. It front-loads the core action ('aggregate', 'grouped', 'subtracted') and states the key merging rule efficiently. Perfectly sized for the tool's purpose.
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?
An output schema exists, so return values are covered. The description captures the essential behavior—aggregation, grouping, subtraction, and merging rules. However, it does not guide the agent on input structure or prerequisites, leaving some gaps given the tool's complexity. Still, the key semantics are present and the annotations fill in safety details.
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 for parameter documentation. However, the description does not mention 'onHand' or 'recipes' at all, nor their structure or purpose. The agent must rely entirely on the schema, which is complex and nested, making this 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 tool's purpose: it aggregates raw quantities across recipes, groups by USDA food category, and subtracts on-hand amounts. It uses a specific verb ('aggregate') and resource, and the merging rule distinguishes it from sibling tools like computeBatchMacros or parseRecipe, making its role 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 implies usage when a consolidated shopping list is needed from recipes and on-hand items, but it does not explicitly state when to use this tool over alternatives or mention any exclusions. It is not misleading, but the guidance is implicit and relies on the agent inferring the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert an amount to grams. Mass units are exact. A volume or a count needs either the food's own USDA portion weights, which you get by passing fdcId, or a sourced density row. When neither is available the answer is unresolved with candidates attached, because a cup of flour and a cup of honey do not weigh the same.
| Name | Required | Description | Default |
|---|---|---|---|
| unit | Yes | Free text such as 'tbsp', 'cups', 'oz', 'medium'. | |
| fdcId | No | When given, this food's own USDA portion weights are tried before the density table. | |
| quantity | Yes | ||
| ingredientName | No |
| Name | Required | Description |
|---|---|---|
| note | Yes | |
| grams | Yes | Null when the conversion could not be sourced. |
| method | Yes | |
| unitKind | Yes | |
| confidence | Yes | |
| densityRow | Yes | |
| fdcPortion | Yes | |
| normalizedUnit | Yes | |
| densityCandidates | Yes | |
| portionCandidates | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the unresolved-with-candidates outcome and explains why different foods weight differently, which adds meaningful behavior beyond the read-only/idempotent/open-world annotations. No contradiction with annotations.
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?
Three focused sentences with the core purpose up front. The flour-vs-honey example earns its place by clarifying why volume conversion is not trivial, though it adds slight length.
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 output schema and read-only/idempotent annotations, the description covers the main conversion logic, edge cases, and required inputs. The only notable gap is the unmentioned role of ingredientName.
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 schema leaves ingredientName and fdcId thin, but the description clarifies that fdcId provides USDA portion weights and that volume/count units need extra data. It does not fully explain ingredientName, but it gives enough to guide correct usage.
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 a clear verb and resource: 'Convert an amount to grams.' It then distinguishes exact mass units from ambiguous volume/count cases, which sets it apart from sibling recipe-parsing and macro tools.
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 gives explicit guidance on when the conversion is straightforward versus when fdcId or a density row is needed<!-- -->—exactly the decision an agent must make. It does not explicitly name sibling alternatives, but the tool's role is clear from context.
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.0computeBatchMacrosgetFoodMacroslookupBarcodeparseIngredientLineparseRecipeplanBatchSizeportionBatchscaleRecipesearchFoodsetCookedYieldshoppingListtoGramsScored across 12 tools
Most tools target distinct pipeline stages—food lookup, parsing, conversion, batch math, portioning, scaling, and shopping—so an agent can generally select by input and output. The only mild ambiguities are getFoodMacros vs lookupBarcode (both expose per-100g macros) and planBatchSize vs portionBatch (both reason about eaters), but the descriptions state the identifier/source and pre-cook/post-cook differences clearly.
All tool names use camelCase and most follow a clear verb+object convention: parseRecipe, searchFood, computeBatchMacros, scaleRecipe. shoppingList is a bare noun and toGrams uses a preposition rather than a verb, so the pattern is consistent in style but not perfectly uniform.
Twelve tools is an appropriate, well-scoped size for a food/macro meal-planning server. Each tool covers one distinct operation with no redundant clusters, and the set is large enough to span a full workflow without feeling bloated.
The server covers the complete recipe-to-shopping lifecycle: finding foods, parsing recipe and ingredient input, converting to grams, computing batch macros, accounting for cooked yield, portioning, scaling, and aggregating a shopping list. Dependent tools explicitly reference the outputs they need, and unresolved results return candidates instead of dead-ending.
Food and nutrition data: search, macros, and comparisons
Natural-language calorie lookup. Send '2 large eggs', get USDA-sourced nutrition data.
Resolve Japanese food names to nutrition facts. All 2,538 foods from Japan's official tables.
USDA FoodData Central nutrition data: search foods, compare macros, and analyze meals.