USDA FoodData Central を情報源とし、指定された食材・指定された分量に対して、信頼できるマクロ栄養素データを返す MCP サーバーです。
このサーバーの仕事はただ一つです。LLM が食事を計画したりレシピを組み立てたりするとき、実在の食品・実在の分量に対する、実際のカロリー・タンパク質・炭水化物・脂質を返します。もっともらしい推測を返すことは絶対にありません。食材の構成やレシピ設計、計算処理は、呼び出し元のモデルの問題です。正しい入力を返すことが、このサーバーの唯一の存在意義です。
mise-en-place は、独自の栄養データベースではありません。USDA FoodData Central の前面に位置するルックアップ・レイヤーで、LLM が食品を検索し、「中玉ねぎ1個」「大さじ2」「6オンス」といった数量をグラムに解決して、でっち上げではなく出典のある本当のマクロ栄養素データを取得できるように設計されています。MCP（stdio）上で動作するため、MCP 対応クライアント（Claude Code、Claude Desktop、その他プロトコルを話せるクライアント）ならどれからでも直接接続できます。
ツールは8つあります：search_foods、get_nutrition、get_nutrition_batch、save_override、save_recipe、get_recipe、get_recipe_history、list_recipes。完全なシグネチャとスキーマは INTERFACES.md にあります。
Related MCP server: nutrition-mcp-server
要件： Python 3.11+、無料の USDA FoodData Central API キー（登録後にすぐ取得できます）。
git clone <this repo>
cd mise-en-place
uv sync # or: pip install -e .
export USDA_API_KEY=<your key>MCP クライアント（例：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-placeクライアントを再起動して新しい接続を認識させたら、あとは作りたいものを尋ねるだけです。サーバー自身の instructions（server.py の _SERVER_INSTRUCTIONS で確認できます）は接続とともに配信され、モデルにツールの正しい使い方を指示します。したがって、チャットに手動で貼り付ける必要は一切ありません。自分のマクロ栄養素ターゲットを使って定期的な食事計画セッションを行う場合は、MEAL_PLANNING_PROMPT.md を参照してください。ターゲットは人ごと・食事ごとに異なるため、サーバーが保存することはありません。そのファイルにのみ存在します。
個人の perg修正・調整や保存済みレシピは ~/.mise-en-place/（MISE_HOME）に置かれ、コミットされることはありません。リポジトリのルートにある masses.toml は、出荷時に同梱されチェックインされている既定のキッチン計量重量表（中玉ねぎ1個、卵1個など）です。人間が書き、出典が明示され、編集することで異議を唱えられる内容になっています。
「カロリーを教えて」系のツールは、実際には答えを知らない質問に対して答えを返すことがよくあります。この サーバーはそうではありません：
栄養値をでっち上げることは絶対にありません。 USDA がその数値を持っていない場合、ツールはエラーを出すか、明示的に「存在しない」と報告します。ゼロをごまかしとして返すことも、事実の代わりに推定値を返すこともありません。
丸め数にフォールバックすることはありません。 分量をグラムに解決できない場合（USDA 自身のポーション用データ、自分で保存した修正、同梱の masses.toml の既定値のいずれでも駄目な場合）は、100g を控えめに適用したり密度を推測するのではなく、エラーを発生させます。
不確かな値は、その都度はっきりと伝えられます。 低い信頼度のマッチ、確信が持てなかった候補、推定された質量 — これらはすべて、検証済みの値と同じ程度に自信ありげに見える数値としてではなく、構造化された注意書きとして呼び出し元モデルに返されます。
修正はツールを恒久的に改善します。 save_override と save_recipe は、同じ食材の将来のすべての検索で再推測するのでなく、失敗を一度だけ修正すれば済むようにします。
モデルが単独で推量するよりも測定可能なかぎり正確です。 手で検証したラベルデータに対する10レシピ atベンチマークでは、Tool の平均誤差は 4.99%: 一方同じ モデルでツールを使わない場合の 8.26% となりました。方法論と現状数値は下記のとおりです。
「値をでっち上げない」というルールは、主張するのもかんたん、静かに破るのもかんたんです。それを支えるものが2つあります。
ライブで再検証されるテストデータ。 masses.toml とテストスイートのゴールデン値の中でこのプロジェクトが引用するすべての USDA ID は、実行のたびに毎回実際の API から再取得され、その ID が主張したものと一致を検証します（tests/test_golden_values.py、tests/test_masses_toml.py）。古くなってしまった引用は、権威し出してそのまま残るのではなく、大きなエラーとして明示的に失敗します。
単なる別のレシピサイトの意見ではなく、実際の製品データと照合して精度を検証しています。 初期の精度確認パスでは、このツールの出力を、人気のある健康レシピサイトの公開栄養数値と比較しました。すると、いくつかのレシピで大きなずれが見つかりました。よ适 して詳しく調べてみると、ずれは逆向きでした。最悪のケースを実際の商品栄養ラベルと手作業で照合すると、このツールの数値が実際に近く、サードパーティのサイトの値が異常値だったのです。つまり、レシピサイトとの比較はそもそも間違ったテストでした。そのサイトの方法論は不透明で、どの商品を対象にしたのか、どんな出来上がり量の制約を採用したのか、背後にどんな栄養データベースがあるのかを知る術がなかったからです。
その結果として構築した本当の精度ベンチマーク（tests/golden_recipes/）は、意図的に分離した2つのソースから作られています。真正のコモディティ食材に対する USDA データ（ジャガイモ、グラニュー糖など、ブランドと呼べるものがないもの）、そして特定の商業商品が plausible に意味があるものに対する実際の商品栄養ラベルデータ（あるブランドのトルティーヤ、パッケージ入り豆腐など）です。USDA をバックにしたツールの一般的な一致を USDA データで検証しても、それは自分自身と一致しているか確認しているだけです。ラベルデータだけが、ブランド化された食材に対して実際に意味のある独立した検証です。このテストのいくつかのレシピには同じ食材が意図的に二つの言い方で含まれています：一般的な名前（"tortilla chips"）と特定の名前（"Mission tortilla chips"）。これにより、ベンチマークはツールの既定の汎用一致と、レシピが名前で商品を要求したときに正しく検索して優先するか、その両方をチェックします。
最新の結果（レシピ10件、ツール装備エージェント vs ツールなしLLM記憶エージェント。両者同じ人為検証済みラベルデータでスコアした、2026-08-21）：
ツール装備エージェントのカロリー/タンパク質/炭水化物/脂質の平均絶対誤差は 4.99% に対して、ツールなしの同じエージェントは 8.26% でした。ツールは10レシピ中7個で優勢で、特にブランド名を調べるのが本当に難しい食材や、脂肪分を間違えて覚えやすい肉cut（鶏もも肉、スカートステーキなど）を含むレシピでは明らかに強いです。無粋な記憶法が同じくらいかそれ以上に優れていた3つレシピは、ツール自体のマッチングが弱いという証拠ではありません。これらは、レシピそのものが「はっきりと数えることができない」数量（重量が指定されていない飾りなど）を殊更に残していて、結果として両条件が余計な推測を強いられベンチマーク全体に無関係なノイズが混入したケースです。そのスコアを当てにする前に注意をすべき1件は、tests/golden_recipes/eval_prompts.json の note_on_TC10 を参照してください。この数値は、フィクスチャとツールの両方が変化し続けるため drift します。恒久的な主張ではなく、現時点での「値」としてください。
知りたいこと | 参照 |
システムの要件、信頼度モデル、マクロ栄養レポート |
|
モジュール構成、データフロー、テスト戦略 |
|
正確なツールシグネチャとデータスキーマ |
|
今何が実装されていて何が残ているか |
|
このコードベースに当たって（人やエージェントが）従うべき規則 |
|
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 nutrient lookup, FDA recall watch, EU FMCG labelling via remote MCP
USDA FoodData Central nutrition data: search foods, compare macros, and analyze meals.