Skip to main content
Glama

Compare USDA Foods

usda_compare_foods
Read-only

Compare nutrients side-by-side for 2–5 foods. Returns a structured table — one row per nutrient, one column per food — formatted as markdown. Best for "spinach vs kale iron" or "which has more protein?" questions. Accepts up to 500 FDC IDs: repeats are dropped, the first 5 distinct IDs are compared, and the rest are returned in deferredIds without being requested from FDC, with a notice naming the follow-up call. Omit nutrients[] to use the 12 most common defaults (energy, protein, fat, saturated fat, carbs, fiber, sugars, sodium, potassium, calcium, iron, vitamin C); a food that lacks the default energy (1008) or total sugars (2000) value has that cell filled from its equivalent nutrient — energy from 2048, then 2047; sugars from 1063 — and each fill is listed in substitutions. Provide nutrients[] with specific FDC IDs to compare different nutrients; an explicit list is compared as given, repeats dropped, without fills. All values are scaled to the same basis, quantity in unit: default 100 g, so unit="oz" alone compares per 100 oz and quantity alone is grams. A Branded food FDC reports per 100 ml (basisUnit "ml") or per 100 of a label unit that fixes neither (basisUnit absent) is compared on that basis without conversion, and a notice names it. If one or more FDC IDs are not found, the comparison proceeds with the valid foods — only throws too_few_foods when fdcIds holds fewer than 2 distinct IDs or fewer than 2 of the compared IDs return data. IDs FDC does not return before the call's deadline (slow Foundation records, most often) or keeps failing on are left out, listed in deferredIds ahead of any past the first 5, and named in a notice; when that leaves fewer than 2 foods, the call fails with retry_deadline_exceeded instead, or with too_few_foods when even answers for those IDs could not make 2 foods.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "fdcIds": "<fdcIds>"
    },
    "name": "usda_compare_foods"
  }
}

Input Schema

NameRequiredDescriptionDefault
unitNoUnit for quantity. Default "g". Does not support "serving" (each food's portion weight differs, so a serving basis would not compare equal amounts).g
fdcIdsYesFDC IDs to compare — 2 to 500 entries (a server configured with strict limits rejects more than 5). Repeats are dropped; the first 5 distinct IDs are compared and the rest are returned in deferredIds. Use usda_search_foods to discover IDs.
quantityNoAmount of food, in unit, that every value is scaled to. Must be positive. Default 100.
nutrientsNoNutrient IDs to include in the comparison. Defaults to the 12 most common: energy (1008), protein (1003), total fat (1004), saturated fat (1258), carbohydrate (1005), fiber (1079), total sugars (2000), sodium (1093), potassium (1092), calcium (1087), iron (1089), vitamin C (1162). Under the defaults, a food missing energy or total sugars has that cell filled from its equivalent nutrient (listed in substitutions); IDs given here are compared as given, repeats dropped. Use usda_list_nutrients to look up other IDs.

Output Schema

NameRequiredDescriptionDefault
basisNoThe common scaling basis applied to all nutrient values.
errorNoPresent when the call failed. Absent on success.
foodsNoThe compared foods, in the same order as the values arrays below.
noticeNoPresent when deferredIds is, or a compared food is not reported per 100 g. First, how many distinct IDs past the first 5 were not requested, which of the first 5 FDC did not return before the deadline or kept failing on, and the call that fetches them; then the basis caveat naming each food not per 100 g: an ml food compared per basis.gramWeight millilitres, or a food whose per-100 basis is unverified, both without conversion.
nutrientsNoNutrient rows — one entry per requested nutrient, with per-food values in the values[] array.
deferredIdsNoDistinct requested IDs this call did not compare, in request order: any of the first 5 FDC did not return before the call's deadline or kept failing on, then those past the first 5, which were never requested from FDC. The comparison leaves them out: they appear in neither foods nor missingData. Call usda_compare_foods with them and the same nutrients, quantity, and unit (pair a single one with an ID already compared), or fetch an unanswered one with usda_get_food. Absent when every distinct ID was requested and FDC answered each one.
missingDataNoFoods or food+nutrient pairs where data was unavailable. A cell filled from an equivalent nutrient is listed in substitutions, not here. Absent when all data was present.
substitutionsNoDefault-row cells filled from an equivalent nutrient because the food does not report the row ID, in nutrients[] then foods[] order. Absent when nothing was filled.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • changedInput schema / properties / fdcIds / description
      Previous value: -"FDC IDs to compare — 2 to 5 foods. Use usda_search_foods to discover IDs."New value: +"FDC IDs to compare — 2 to 500 entries (a server configured with strict limits rejects more than 5). Repeats are dropped; the first 5 distinct IDs are compared and the rest are returned in deferredIds. Use usda_search_foods to discover IDs."
    • changedInput schema / properties / fdcIds / maxItems
      Previous value: -5New value: +500
    • changedInput schema / properties / nutrients / description
      Previous value: -"Nutrient IDs to include in the comparison. Defaults to the 12 most common: energy (1008), protein (1003), total fat (1004), saturated fat (1258), carbohydrate (1005), fiber (1079), total sugars (2000), sodium (1093), potassium (1092), calcium (1087), iron (1089), vitamin C (1162). Under the defaults, a food missing energy or total sugars has that cell filled from its equivalent nutrient (listed in substitutions); IDs given here are compared as given. Use usda_list_nutrients to look up other IDs."New value: +"Nutrient IDs to include in the comparison. Defaults to the 12 most common: energy (1008), protein (1003), total fat (1004), saturated fat (1258), carbohydrate (1005), fiber (1079), total sugars (2000), sodium (1093), potassium (1092), calcium (1087), iron (1089), vitamin C (1162). Under the defaults, a food missing energy or total sugars has that cell filled from its equivalent nutrient (listed in substitutions); IDs given here are compared as given, repeats dropped. Use usda_list_nutrients to look up other IDs."
    • changedOutput schema / properties / deferredIds / description
      Previous value: -"Distinct requested IDs FDC did not return before the call's deadline or kept failing on, in request order. The comparison leaves them out: they appear in neither foods nor missingData. Fetch them with usda_get_food, or call usda_compare_foods again. Absent when FDC answered every ID."New value: +"Distinct requested IDs this call did not compare, in request order: any of the first 5 FDC did not return before the call's deadline or kept failing on, then those past the first 5, which were never requested from FDC. The comparison leaves them out: they appear in neither foods nor missingData. Call usda_compare_foods with them and the same nutrients, quantity, and unit (pair a single one with an ID already compared), or fetch an unanswered one with usda_get_food. Absent when every distinct ID was requested and FDC answered each one."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `too_few_foods`: Fewer than 2 of the provided FDC IDs returned data, making comparison impossible. `retry_deadline_exceeded`: FDC did not answer within the call's 45-second budget, across every attempt. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `too_few_foods`: fdcIds holds fewer than 2 distinct IDs, or fewer than 2 of the compared IDs returned data, making comparison impossible. `retry_deadline_exceeded`: FDC did not answer within the call's 45-second budget, across every attempt. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / notice / description
      Previous value: -"Present when deferredIds is, or a compared food is not reported per 100 g. First, the IDs in deferredIds and the call that fetches them; then the basis caveat naming each food not per 100 g: an ml food compared per basis.gramWeight millilitres, or a food whose per-100 basis is unverified, both without conversion."New value: +"Present when deferredIds is, or a compared food is not reported per 100 g. First, how many distinct IDs past the first 5 were not requested, which of the first 5 FDC did not return before the deadline or kept failing on, and the call that fetches them; then the basis caveat naming each food not per 100 g: an ml food compared per basis.gramWeight millilitres, or a food whose per-100 basis is unverified, both without conversion."
  2. Changed4 schema fields changed
    • addedOutput schema / properties / deferredIds
      Added value: +{
      +  "description": "Distinct requested IDs FDC did not return before the call's deadline or kept failing on, in request order. The comparison leaves them out: they appear in neither foods nor missingData. Fetch them with usda_get_food, or call usda_compare_foods again. Absent when FDC answered every ID.",
      +  "items": {
      +    "type": "number"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `too_few_foods`: Fewer than 2 of the provided FDC IDs returned data, making comparison impossible. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `too_few_foods`: Fewer than 2 of the provided FDC IDs returned data, making comparison impossible. `retry_deadline_exceeded`: FDC did not answer within the call's 45-second budget, across every attempt. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "too_few_foods"
      -]New value: +[
      +  "too_few_foods",
      +  "retry_deadline_exceeded"
      +]
    • changedOutput schema / properties / notice / description
      Previous value: -"Basis caveat naming each compared food not reported per 100 g: an ml food compared per basis.gramWeight millilitres, or a food whose per-100 basis is unverified, both without conversion."New value: +"Present when deferredIds is, or a compared food is not reported per 100 g. First, the IDs in deferredIds and the call that fetches them; then the basis caveat naming each food not per 100 g: an ml food compared per basis.gramWeight millilitres, or a food whose per-100 basis is unverified, both without conversion."
  3. Changed7 schema fields changed
    • changedInput schema / properties / nutrients / description
      Previous value: -"Nutrient IDs to include in the comparison. Defaults to the 12 most common: energy (1008), protein (1003), total fat (1004), saturated fat (1258), carbohydrate (1005), fiber (1079), total sugars (2000), sodium (1093), potassium (1092), calcium (1087), iron (1089), vitamin C (1162). Use usda_list_nutrients to look up other IDs."New value: +"Nutrient IDs to include in the comparison. Defaults to the 12 most common: energy (1008), protein (1003), total fat (1004), saturated fat (1258), carbohydrate (1005), fiber (1079), total sugars (2000), sodium (1093), potassium (1092), calcium (1087), iron (1089), vitamin C (1162). Under the defaults, a food missing energy or total sugars has that cell filled from its equivalent nutrient (listed in substitutions); IDs given here are compared as given. Use usda_list_nutrients to look up other IDs."
    • changedOutput schema / properties / basis / properties / gramWeight / description
      Previous value: -"Gram weight resolved from quantity and unit — all nutrient values are per this many grams."New value: +"Gram weight resolved from quantity and unit — every column is per this many grams, except that a food with basisUnit \"ml\" is per this many millilitres and one with no basisUnit per this many label units, compared without conversion."
    • addedOutput schema / properties / foods / items / properties / basisUnit
      Added value: +{
      +  "description": "What the per-100 nutrient values are measured in: \"g\" for every non-Branded food and for Branded labels in g/GRM/GM, \"ml\" for Branded labels in ml/MLT. Absent when the label unit (e.g. IU, MG) fixes neither, so the basis is unverified.",
      +  "enum": [
      +    "g",
      +    "ml"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / foods / items / properties / servingSizeUnit
      Added value: +{
      +  "description": "Label serving unit as FDC reports it (e.g. \"GRM\", \"MLT\", \"IU\"); it sets basisUnit. Branded items only.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / missingData / description
      Previous value: -"Foods or food+nutrient pairs where data was unavailable. Absent when all data was present."New value: +"Foods or food+nutrient pairs where data was unavailable. A cell filled from an equivalent nutrient is listed in substitutions, not here. Absent when all data was present."
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Basis caveat naming each compared food not reported per 100 g: an ml food compared per basis.gramWeight millilitres, or a food whose per-100 basis is unverified, both without conversion.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / substitutions
      Added value: +{
      +  "description": "Default-row cells filled from an equivalent nutrient because the food does not report the row ID, in nutrients[] then foods[] order. Absent when nothing was filled.",
      +  "items": {
      +    "additionalProperties": false,
      +    "description": "One default-row cell filled from an equivalent nutrient.",
      +    "properties": {
      +      "fdcId": {
      +        "description": "FDC ID of the food whose cell was filled.",
      +        "type": "number"
      +      },
      +      "requested": {
      +        "description": "Nutrient ID of the row: 1008 (energy) or 2000 (total sugars).",
      +        "type": "number"
      +      },
      +      "used": {
      +        "description": "Nutrient ID the value was taken from: 2048 or 2047 for energy, 1063 for sugars.",
      +        "type": "number"
      +      }
      +    },
      +    "required": [
      +      "fdcId",
      +      "requested",
      +      "used"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  4. Changed5 schema fields changed
    • changedInput schema / properties / quantity / description
      Previous value: -"Gram basis for comparison. All values scaled to this amount. Must be positive. Default 100."New value: +"Amount of food, in unit, that every value is scaled to. Must be positive. Default 100."
    • changedInput schema / properties / unit / description
      Previous value: -"Unit for quantity. Default \"g\". Does not support \"serving\" (use a fixed gram basis for consistent comparison)."New value: +"Unit for quantity. Default \"g\". Does not support \"serving\" (each food's portion weight differs, so a serving basis would not compare equal amounts)."
    • changedOutput schema / properties / basis / properties / gramWeight / description
      Previous value: -"Gram weight resolved from quantity+unit — all nutrient values are per this many grams."New value: +"Gram weight resolved from quantity and unit — all nutrient values are per this many grams."
    • changedOutput schema / properties / basis / properties / quantity / description
      Previous value: -"Numeric quantity provided in the request."New value: +"Quantity applied, in unit — the requested value or the default 100."
    • changedOutput schema / properties / basis / properties / unit / description
      Previous value: -"Unit provided in the request (g, oz, lb, or kg)."New value: +"Unit applied (g, oz, lb, or kg) — the requested value or the default \"g\"."
  5. Changed4 schema fields changed
    • removedOutput schema / properties / missingData / items / properties / nutrientId / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / missingData / items / properties / nutrientId / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / nutrients / items / properties / values / items / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / nutrients / items / properties / values / items / type
      Added value: +[
      +  "number",
      +  "null"
      +]
  6. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "basis",
      +      "foods",
      +      "nutrients"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `too_few_foods`: Fewer than 2 of the provided FDC IDs returned data, making comparison impossible. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "too_few_foods"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "basis",
      -  "foods",
      -  "nutrients"
      -]
  7. First observed

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint and openWorldHint; the description goes far beyond them, disclosing ID deduplication and truncation to the first 5, deferredIds population, out-of-band nutrient fills into substitutions, non-converted Branded ml bases, and the exact error taxonomy (too_few_foods vs retry_deadline_exceeded). That is precisely the behavior an agent cannot infer from readOnlyHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening is well front-loaded, but the body becomes a single dense paragraph of semicolon-chained clauses, and the final sentence about deadline-exceeded IDs is a near-unparseable run-on. Nearly every clause carries real behavioral information, so the problem is packaging rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with four parameters, a 5-ID truncation rule, two distinct error codes and an output schema, the description covers the decision-relevant behavior end to end: input normalization, basis scaling, substitution policy, partial-failure handling, and degraded-failure handling. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond it: the scaling rule that unit="oz" alone means per 100 oz, that the default nutrient list triggers substitution fills while an explicit list does not, and that repeats are dropped before the 5-ID cap. The one inconsistency is the opening "2-5 foods" framing against a 500-ID maximum, which the later text resolves only after some parsing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb (compare), a specific resource (nutrients) and a concrete output shape (one row per nutrient, one column per food, markdown table). It is clearly distinguishable from usda_search_foods (ID discovery) and usda_get_food (single-food detail), so an agent can route correctly without opening another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete selection cues with example questions ("spinach vs kale iron", "which has more protein?"), which tells the agent exactly what class of question belongs here. It does not state an explicit when-not-to-use or name a sibling alternative in the description body (that hint lives only in the fdcIds schema text), so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.