Skip to main content
Glama

Get USDA Foods (Batch)

usda_get_foods
Read-only

Fetch nutrient profiles for several foods at once. More efficient than calling usda_get_food N times when you already have multiple FDC IDs. Accepts up to 500 IDs: repeats are dropped, the first 20 distinct IDs are fetched, and the rest are returned in deferredIds for a follow-up call. IDs FDC does not return before the call's deadline (slow Foundation records, most often) or keeps failing on also come back in deferredIds, ahead of those, named in a notice. Values are per 100 of each food's basisUnit, with no portion scaling: per 100 g (basisUnit "g"), except Branded foods FDC reports per 100 ml (basisUnit "ml") or per 100 of a label unit that fixes neither (basisUnit absent, basis unverified). Use the nutrients[] filter to limit response size — strongly recommended for batch calls; requested IDs a food does not report are listed in its missingNutrients. Set provenance=true to add to each nutrient how FDC obtained its value (derivation code, description, and source), its sample count (dataPoints), and the sample min, max, and median, each only where FDC sends it. For side-by-side comparison with a formatted table, use usda_compare_foods instead. Failed IDs (not found or no data) are reported in the failed[] array rather than aborting the entire batch.

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_get_foods"
  }
}

Input Schema

NameRequiredDescriptionDefault
fdcIdsYesFDC IDs to fetch — 2 to 500 entries (a server configured with strict limits rejects more than 20). Repeats are dropped; the first 20 distinct IDs are fetched and the rest are returned in deferredIds. Use usda_search_foods to discover IDs.
nutrientsNoFilter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008]). Strongly recommended — full profiles can be large. Use usda_list_nutrients to look up IDs. Requested IDs a food does not report are listed in its missingNutrients.
provenanceNoAdd to each nutrient what FDC records about its value: derivation (code, description, source), dataPoints (sample count), and min, max, median (sample spread, per 100 of basisUnit like amount). Each is present only where FDC sends it: Survey (FNDDS) foods send none, Branded foods only a derivation. Off by default; it makes the response two to three times as large.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
foodsNoSuccessfully fetched foods.
failedNoIDs that returned no data. Check these with usda_search_foods to verify they exist.
noticeNoDeferral notice when deferredIds is present: how many of the distinct IDs past the first 20 were not fetched, which fetched IDs FDC did not return before the deadline or kept failing on, and the call that fetches them.
deferredIdsNoDistinct requested IDs this call did not fetch, in request order: any FDC did not return before the call's deadline or kept failing on, then those past the first 20, which were never requested from FDC. foods and failed cover neither. Pass them to usda_get_foods again, or a single one to usda_get_food, with the same nutrients and provenance. Absent when every distinct ID was fetched.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changed
    • addedInput schema / properties / provenance
      Added value: +{
      +  "default": false,
      +  "description": "Add to each nutrient what FDC records about its value: derivation (code, description, source), dataPoints (sample count), and min, max, median (sample spread, per 100 of basisUnit like amount). Each is present only where FDC sends it: Survey (FNDDS) foods send none, Branded foods only a derivation. Off by default; it makes the response two to three times as large.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / deferredIds / description
      Previous value: -"Distinct requested IDs this call did not fetch, in request order: any FDC did not return before the call's deadline or kept failing on, then those past the first 20, which were never requested from FDC. foods and failed cover neither. Pass them to usda_get_foods again, or a single one to usda_get_food. Absent when every distinct ID was fetched."New value: +"Distinct requested IDs this call did not fetch, in request order: any FDC did not return before the call's deadline or kept failing on, then those past the first 20, which were never requested from FDC. foods and failed cover neither. Pass them to usda_get_foods again, or a single one to usda_get_food, with the same nutrients and provenance. Absent when every distinct ID was fetched."
    • addedOutput schema / properties / foods / items / properties / nutrients / items / properties / dataPoints
      Added value: +{
      +  "description": "Number of samples behind the value, as FDC sends it; with provenance=true only. SR Legacy sends it on every value (0 for calculated and assumed values), Foundation on analytical values; Branded and Survey (FNDDS) send none. A count, never scaled.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / foods / items / properties / nutrients / items / properties / derivation
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "How FDC obtained the value; with provenance=true only. Foundation and Branded send one on every value, SR Legacy on some (a measured SR Legacy value can carry only dataPoints), Survey (FNDDS) on none. Absent when FDC sends none, never inferred. Code \"Z\" is an assumed zero, not a measurement.",
      +  "properties": {
      +    "code": {
      +      "description": "FDC derivation code (e.g. \"A\", \"NC\", \"Z\", \"LCCS\").",
      +      "type": "string"
      +    },
      +    "description": {
      +      "description": "What the code means, as FDC words it (e.g. \"Analytical\", \"Calculated\", \"Summed\").",
      +      "type": "string"
      +    },
      +    "source": {
      +      "description": "Source category FDC files the derivation under (e.g. \"Analytical or derived from analytical\", \"Calculated or imputed\", \"Assumed zero\"). Absent when FDC sends none.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "description"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / foods / items / properties / nutrients / items / properties / max
      Added value: +{
      +  "description": "Highest sample value, in the same unit and basis as amount and scaled with it; with provenance=true only. Foundation sends it on most values, SR Legacy on some; Branded and Survey (FNDDS) send none.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / foods / items / properties / nutrients / items / properties / median
      Added value: +{
      +  "description": "Median sample value, in the same unit and basis as amount and scaled with it; with provenance=true only. Foundation sends it on most values; SR Legacy, Branded, and Survey (FNDDS) send none.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / foods / items / properties / nutrients / items / properties / min
      Added value: +{
      +  "description": "Lowest sample value, in the same unit and basis as amount and scaled with it; with provenance=true only. Foundation sends it on most values, SR Legacy on some; Branded and Survey (FNDDS) send none.",
      +  "type": "number"
      +}
  2. Changed4 schema fields changed
    • changedOutput schema / properties / deferredIds / description
      Previous value: -"Distinct requested IDs past the first 20, in request order, not fetched by this call — foods and failed cover only the fetched IDs. Pass them to usda_get_foods again, or a single one to usda_get_food. Absent when every distinct ID was fetched."New value: +"Distinct requested IDs this call did not fetch, in request order: any FDC did not return before the call's deadline or kept failing on, then those past the first 20, which were never requested from FDC. foods and failed cover neither. Pass them to usda_get_foods again, or a single one to usda_get_food. Absent when every distinct ID was fetched."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode."New value: +"Machine-readable failure mode. Declared by this tool: `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."
    • addedOutput schema / properties / error / properties / data / properties / reason / examples
      Added value: +[
      +  "retry_deadline_exceeded"
      +]
    • changedOutput schema / properties / notice / description
      Previous value: -"Deferral notice when more than 20 distinct IDs were requested: how many were fetched, and the call that fetches the IDs in deferredIds."New value: +"Deferral notice when deferredIds is present: how many of the distinct IDs past the first 20 were not fetched, which fetched IDs FDC did not return before the deadline or kept failing on, and the call that fetches them."
  3. Changed10 schema fields changed
    • changedInput schema / properties / fdcIds / description
      Previous value: -"FDC IDs to fetch — 2 to 20 IDs. Use usda_search_foods to discover IDs."New value: +"FDC IDs to fetch — 2 to 500 entries (a server configured with strict limits rejects more than 20). Repeats are dropped; the first 20 distinct IDs are fetched and the rest are returned in deferredIds. Use usda_search_foods to discover IDs."
    • changedInput schema / properties / fdcIds / maxItems
      Previous value: -20New value: +500
    • changedInput schema / properties / nutrients / description
      Previous value: -"Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008]). Strongly recommended — full profiles can be large. Use usda_list_nutrients to look up IDs."New value: +"Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008]). Strongly recommended — full profiles can be large. Use usda_list_nutrients to look up IDs. Requested IDs a food does not report are listed in its missingNutrients."
    • addedOutput schema / properties / deferredIds
      Added value: +{
      +  "description": "Distinct requested IDs past the first 20, in request order, not fetched by this call — foods and failed cover only the fetched IDs. Pass them to usda_get_foods again, or a single one to usda_get_food. Absent when every distinct ID was fetched.",
      +  "items": {
      +    "type": "number"
      +  },
      +  "type": "array"
      +}
    • 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 / missingNutrients
      Added value: +{
      +  "description": "Requested nutrient IDs this food's profile does not report, deduplicated, in request order. Absent when nutrients[] was omitted or every requested ID is present.",
      +  "items": {
      +    "type": "number"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / foods / items / properties / nutrients / description
      Previous value: -"Nutrient values per 100g."New value: +"Nutrient values per 100 of basisUnit."
    • changedOutput schema / properties / foods / items / properties / nutrients / items / properties / amount / description
      Previous value: -"Amount per 100g."New value: +"Amount per 100 of basisUnit."
    • 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"
      +}
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Deferral notice when more than 20 distinct IDs were requested: how many were fetched, and the call that fetches the IDs in deferredIds.",
      +  "type": "string"
      +}
  4. 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": [
      +      "foods",
      +      "failed"
      +    ]
      +  },
      +  {
      +    "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.",
      +          "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: -[
      -  "foods",
      -  "failed"
      -]
  5. First observed

TDQS

A4.6/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 adds the operationally critical behavior: dedupe, a 20-distinct-ID fetch cap with the remainder in deferredIds, deadline-related deferrals and repeated failures surfaced in a notice, and that failures land in failed[] rather than aborting the batch. It also documents the unit semantics (per 100 of basisUnit, Branded per 100 ml, unverified basis) and that provenance=true multiplies response size two-to-threefold — none of which the annotations convey.

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

Conciseness4/5

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

Front-loaded with the core purpose and the batching payoff, and most sentences carry distinct information (caps, deferrals, units, filtering, provenance). It is dense and slightly run-on — the basisUnit/per-100 sentence packs three cases into one clause chain, and a few points echo the schema — but nothing is filler.

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 3-parameter batch tool with an output schema and read-only annotations, the description covers everything an agent needs: batch limits and overflow behavior, partial-failure handling, filtering guidance, unit interpretation, and provenance cost. Return structures (deferredIds, failed[], missingNutrients) are named so callers know what to inspect.

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

Parameters3/5

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

Schema description coverage is 100% and the parameter descriptions already explain the 2–500 range, repeat dropping, the 20-distinct fetch cap, the nutrients filter, missingNutrients, and provenance cost. The prose largely restates those same semantics (missingNutrients, provenance size cost) rather than adding format or edge-case detail the schema lacks, so the high-coverage baseline of 3 applies.

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?

States a specific verb and resource ('Fetch nutrient profiles for several foods at once') and explicitly distinguishes itself from the single-item sibling ('More efficient than calling usda_get_food N times') and from usda_compare_foods ('side-by-side comparison with a formatted table'). An agent can pick the right tool without opening schemas.

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

Usage Guidelines5/5

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

Gives explicit when-to-use (you already hold multiple FDC IDs) and when-not (use usda_compare_foods for a formatted side-by-side table), plus a strong recommendation to apply the nutrients[] filter for batch calls. Alternatives are named and the selecting condition is stated.

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.