Skip to main content
Glama

openfoodfacts-mcp-server

Compare Food Products Side-by-Side

off_compare_products
Read-onlyIdempotent

Side-by-side nutrition and scoring comparison for 2–10 products per call by barcode; a repeated barcode is compared once, so two identical barcodes yield one row, and barcodes past the 10th distinct one are listed in unprocessed rather than fetched. Returns a normalized table of energy (kcal), fat, saturated fat, carbohydrates, sugars, salt, protein, and fiber per 100 g, or per 100 ml for liquids, plus Nutri-Score, NOVA group, and Green-Score. Open Food Facts returns one preparation state per read, so figures for the prepared product arrive in a prepared object on the row, with the same columns and basis, and never fill an as-sold field; a row whose read returned only prepared figures gets one more product read, of the as-sold set its record stores, once the read of every barcode has settled, with stored_as_sold saying how it went. Designed for "which of these cereals is healthiest?" or "compare these pasta brands" workflows. Missing nutrition data for any product is preserved as absent — comparisons are not imputed. A batch is not all-or-nothing: barcodes that resolve are returned even when others fail, with confirmed-missing barcodes listed in not_found and failed fetches listed separately in failed. Scores carry regional formula caveats. Data under ODbL 1.0 — cite Open Food Facts in downstream use.

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": {
      "barcodes": "<barcodes>"
    },
    "name": "off_compare_products"
  }
}

Input Schema

NameRequiredDescriptionDefault
barcodesYesBarcodes to compare, returned as one row each in input order; a repeated barcode is compared once, so two identical barcodes yield one row. One call compares at most 10 distinct barcodes: up to 100 are accepted, and those past the 10th distinct one are returned in unprocessed without being fetched. Example: ["3017620422003", "7622210100146"].

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
failedNoBarcodes whose fetch failed, with the per-barcode reason. Absent when every fetch completed. A barcode listed here is unknown, not absent from Open Food Facts — retry it with off_get_product before concluding anything about the product. A stored as-sold set that could not be read is not a failed fetch: it stays on its row as stored_as_sold.
productsNoComparison rows in input order — one per distinct barcode whose fetch completed, whether or not a record exists. Barcodes whose fetch failed have no row here; they appear in failed. Barcodes past the cap appear in unprocessed.
not_foundNoBarcodes Open Food Facts answered for, confirming no contributor record exists. Not an error — the product may exist but not yet be entered. Never used for a fetch that failed.
succeededNoNumber of barcodes that resolved to a found product.
unprocessedNoDistinct barcodes past the 10th, in input order — never fetched, so nothing is known about them. Absent when the batch held 10 or fewer distinct barcodes. Compare them in another off_compare_products call (2–10 barcodes), or look a single one up with off_get_product.
mirror_snapshotNoPresent only when a row's source is "off_mirror". States that those rows come from the local copy as of their mirror_as_of, so an edit made to them since then is not reflected.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / products / items / properties / mirror_as_of / description
      Previous value: -"ISO 8601 time of the newest Open Food Facts change the local copy reflects. Present only when source is \"off_mirror\"."New value: +"ISO 8601 time up to which the local copy reflects every product contributed or edited on Open Food Facts. Present only when source is \"off_mirror\"."
  2. Changed15 schema fields changed
    • changedOutput schema / properties / failed / description
      Previous value: -"Barcodes whose fetch failed, with the per-barcode reason. Absent when every fetch completed. A barcode listed here is unknown, not absent from Open Food Facts — retry it with off_get_product before concluding anything about the product."New value: +"Barcodes whose fetch failed, with the per-barcode reason. Absent when every fetch completed. A barcode listed here is unknown, not absent from Open Food Facts — retry it with off_get_product before concluding anything about the product. A stored as-sold set that could not be read is not a failed fetch: it stays on its row as stored_as_sold."
    • addedOutput schema / properties / failed / items / properties / retryAfter
      Added value: +{
      +  "description": "Whole seconds to wait before retrying this barcode: the time until this server's own product budget frees a slot, or the Retry-After Open Food Facts sent with a 429. Absent when the failure named no wait.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / mirror_snapshot
      Added value: +{
      +  "description": "Present only when a row's source is \"off_mirror\". States that those rows come from the local copy as of their mirror_as_of, so an edit made to them since then is not reflected.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / products / items / properties / carbohydrates_100g / description
      Previous value: -"Total carbohydrates in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."New value: +"Total carbohydrates in grams per 100 g, or per 100 ml for liquids, as sold. When the product read returned only prepared figures, read from the record's stored as-sold set instead (see stored_as_sold). Absent when not entered, or when that stored set was not read."
    • changedOutput schema / properties / products / items / properties / energy_kcal_100g / description
      Previous value: -"Energy in kcal per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."New value: +"Energy in kcal per 100 g, or per 100 ml for liquids, as sold. When the product read returned only prepared figures, read from the record's stored as-sold set instead (see stored_as_sold). Absent when not entered, or when that stored set was not read."
    • changedOutput schema / properties / products / items / properties / fat_100g / description
      Previous value: -"Total fat in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."New value: +"Total fat in grams per 100 g, or per 100 ml for liquids, as sold. When the product read returned only prepared figures, read from the record's stored as-sold set instead (see stored_as_sold). Absent when not entered, or when that stored set was not read."
    • changedOutput schema / properties / products / items / properties / fiber_100g / description
      Previous value: -"Dietary fiber in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."New value: +"Dietary fiber in grams per 100 g, or per 100 ml for liquids, as sold. When the product read returned only prepared figures, read from the record's stored as-sold set instead (see stored_as_sold). Absent when not entered, or when that stored set was not read."
    • addedOutput schema / properties / products / items / properties / mirror_as_of
      Added value: +{
      +  "description": "ISO 8601 time of the newest Open Food Facts change the local copy reflects. Present only when source is \"off_mirror\".",
      +  "type": "string"
      +}
    • changedOutput schema / properties / products / items / properties / prepared / description
      Previous value: -"Figures for the prepared product, on the same columns and basis as the as-sold fields, read from Open Food Facts' *_prepared_100g keys and never derived or substituted for an as-sold figure. Open Food Facts returns one preparation state per read, so as-sold fields absent beside this object mean this read returned none, not that the record holds none. Absent when the read carried none of these figures."New value: +"Figures for the prepared product, on the same columns and basis as the as-sold fields, read from Open Food Facts' *_prepared_100g keys and never derived or substituted for an as-sold figure. Open Food Facts returns one preparation state per read, so when the product read returned only prepared figures the record's stored as-sold set is read for the as-sold fields, and stored_as_sold says how that went. Absent when the read carried none of these figures."
    • changedOutput schema / properties / products / items / properties / proteins_100g / description
      Previous value: -"Protein in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."New value: +"Protein in grams per 100 g, or per 100 ml for liquids, as sold. When the product read returned only prepared figures, read from the record's stored as-sold set instead (see stored_as_sold). Absent when not entered, or when that stored set was not read."
    • changedOutput schema / properties / products / items / properties / salt_100g / description
      Previous value: -"Salt in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."New value: +"Salt in grams per 100 g, or per 100 ml for liquids, as sold. When the product read returned only prepared figures, read from the record's stored as-sold set instead (see stored_as_sold). Absent when not entered, or when that stored set was not read."
    • changedOutput schema / properties / products / items / properties / saturated_fat_100g / description
      Previous value: -"Saturated fat in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."New value: +"Saturated fat in grams per 100 g, or per 100 ml for liquids, as sold. When the product read returned only prepared figures, read from the record's stored as-sold set instead (see stored_as_sold). Absent when not entered, or when that stored set was not read."
    • addedOutput schema / properties / products / items / properties / source
      Added value: +{
      +  "description": "Where this row was read: \"off_api\", Open Food Facts itself, or \"off_mirror\", this server's local copy of the Open Food Facts export, which serves a barcode it holds on a deployment that keeps one, so one comparison can mix the two. The stored as-sold read behind stored_as_sold, when one runs, reads the same source. Present on every row whose found is true.",
      +  "enum": [
      +    "off_api",
      +    "off_mirror"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / products / items / properties / stored_as_sold
      Added value: +{
      +  "description": "How the read of the record's stored as-sold figures went for this row. Present only when its product read returned prepared figures and no as-sold one, which is when that second read of the record's stored nutrition sets runs (Open Food Facts serves one preparation state per product read, and prepared wins).",
      +  "oneOf": [
      +    {
      +      "additionalProperties": false,
      +      "description": "The as-sold fields hold one stored set, never merged: per 100 g, or per 100 ml for liquids, when the record stores it so, else a serving of at least 5 g or ml scaled to 100 as Open Food Facts scales it, from the manufacturer, packaging, USDA, or another non-estimate source, in that order. Each nutrient is the entered value, or the one Open Food Facts computed when none was entered; IU and % DV figures are left out.",
      +      "properties": {
      +        "status": {
      +          "const": "read",
      +          "description": "One stored as-sold set was read into the as-sold fields.",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "status"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "additionalProperties": false,
      +      "description": "Open Food Facts stores no entered as-sold figures for it that can be given per 100 g, or per 100 ml for liquids: the record stores no sets, or only prepared ones, ones estimated from the ingredients, servings under 5 g or ml, or figures in units that do not convert. The as-sold fields stay absent because nothing is entered.",
      +      "properties": {
      +        "status": {
      +          "const": "none",
      +          "description": "The record stores no as-sold set the as-sold fields can be read from.",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "status"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "additionalProperties": false,
      +      "description": "The as-sold figures the record can still hold were not read, so the prepared figures are all this call holds. Never a failed call.",
      +      "properties": {
      +        "error": {
      +          "description": "What went wrong reading the stored sets and what to do about it.",
      +          "type": "string"
      +        },
      +        "reason": {
      +          "description": "Declared failure reason — one of upstream_error, upstream_timeout, upstream_rejected, rate_limited.",
      +          "type": "string"
      +        },
      +        "retryAfter": {
      +          "description": "Whole seconds to wait before reading again: the time until this server's own product budget frees a slot, or the Retry-After Open Food Facts sent with a 429. Absent when the failure named no wait.",
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        "status": {
      +          "const": "unread",
      +          "description": "The stored sets could not be read; the call itself succeeded.",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "status",
      +        "reason",
      +        "error"
      +      ],
      +      "type": "object"
      +    }
      +  ]
      +}
    • changedOutput schema / properties / products / items / properties / sugars_100g / description
      Previous value: -"Total sugars in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."New value: +"Total sugars in grams per 100 g, or per 100 ml for liquids, as sold. When the product read returned only prepared figures, read from the record's stored as-sold set instead (see stored_as_sold). Absent when not entered, or when that stored set was not read."
  3. Changed10 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_error`: Open Food Facts returns a 5xx other than 501 or 504, serves an HTML error page with a 2xx or 5xx status, answers 2xx with a malformed envelope, or is unreachable for a barcode — reported in that barcode's failed entry rather than failing the call. `upstream_timeout`: Open Food Facts did not answer a barcode within the request deadline, or answered 408, 425, or 504 — reported in that barcode's failed entry rather than failing the call. `upstream_rejected`: Open Food Facts refuses a barcode with a 4xx other than 404, 408, 425, or 429, or with 501 Not Implemented — reported in that barcode's failed entry rather than failing the call. `rate_limited`: This server's own per-minute product budget is spent, or Open Food Facts answers 429 — reported in that barcode's failed entry rather than failing the call. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_error`: Open Food Facts returns a 5xx other than 501 or 504, serves an HTML error page with a 2xx or 5xx status, answers 2xx with a malformed envelope, closes the connection before finishing its answer, or is unreachable for a barcode — reported in that barcode's failed entry rather than failing the call. `upstream_timeout`: Open Food Facts did not answer a barcode within the request or retry deadline, or answered 408, 425, or 504 — reported in that barcode's failed entry rather than failing the call. `upstream_rejected`: Open Food Facts refuses a barcode with a 4xx other than 404, 408, 425, or 429, or with 501 Not Implemented — reported in that barcode's failed entry rather than failing the call. `rate_limited`: This server's own per-minute product budget is spent, or Open Food Facts answers 429 — reported in that barcode's failed entry rather than failing the call. Other values are possible when a failure originates below the handler."
    • addedOutput schema / properties / products / items / properties / carbohydrates_100g
      Added value: +{
      +  "description": "Total carbohydrates in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared).",
      +  "type": "number"
      +}
    • changedOutput schema / properties / products / items / properties / energy_kcal_100g / description
      Previous value: -"Energy in kcal per 100 g, or per 100 ml for liquids. Absent when not entered."New value: +"Energy in kcal per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."
    • changedOutput schema / properties / products / items / properties / fat_100g / description
      Previous value: -"Total fat in grams per 100 g, or per 100 ml for liquids. Absent when not entered."New value: +"Total fat in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."
    • changedOutput schema / properties / products / items / properties / fiber_100g / description
      Previous value: -"Dietary fiber in grams per 100 g, or per 100 ml for liquids. Often absent."New value: +"Dietary fiber in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."
    • addedOutput schema / properties / products / items / properties / prepared
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Figures for the prepared product, on the same columns and basis as the as-sold fields, read from Open Food Facts' *_prepared_100g keys and never derived or substituted for an as-sold figure. Open Food Facts returns one preparation state per read, so as-sold fields absent beside this object mean this read returned none, not that the record holds none. Absent when the read carried none of these figures.",
      +  "properties": {
      +    "carbohydrates_100g": {
      +      "description": "Total carbohydrates in grams per 100 g, or per 100 ml for liquids, as prepared. Absent when this read returned no such figure.",
      +      "type": "number"
      +    },
      +    "energy_kcal_100g": {
      +      "description": "Energy in kcal per 100 g, or per 100 ml for liquids, as prepared. Absent when this read returned no such figure.",
      +      "type": "number"
      +    },
      +    "fat_100g": {
      +      "description": "Total fat in grams per 100 g, or per 100 ml for liquids, as prepared. Absent when this read returned no such figure.",
      +      "type": "number"
      +    },
      +    "fiber_100g": {
      +      "description": "Dietary fiber in grams per 100 g, or per 100 ml for liquids, as prepared. Absent when this read returned no such figure.",
      +      "type": "number"
      +    },
      +    "proteins_100g": {
      +      "description": "Protein in grams per 100 g, or per 100 ml for liquids, as prepared. Absent when this read returned no such figure.",
      +      "type": "number"
      +    },
      +    "salt_100g": {
      +      "description": "Salt in grams per 100 g, or per 100 ml for liquids, as prepared. Absent when this read returned no such figure.",
      +      "type": "number"
      +    },
      +    "saturated_fat_100g": {
      +      "description": "Saturated fat in grams per 100 g, or per 100 ml for liquids, as prepared. Absent when this read returned no such figure.",
      +      "type": "number"
      +    },
      +    "sugars_100g": {
      +      "description": "Total sugars in grams per 100 g, or per 100 ml for liquids, as prepared. Absent when this read returned no such figure.",
      +      "type": "number"
      +    }
      +  },
      +  "type": "object"
      +}
    • changedOutput schema / properties / products / items / properties / proteins_100g / description
      Previous value: -"Protein in grams per 100 g, or per 100 ml for liquids. Absent when not entered."New value: +"Protein in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."
    • changedOutput schema / properties / products / items / properties / salt_100g / description
      Previous value: -"Salt in grams per 100 g, or per 100 ml for liquids. Absent when not entered."New value: +"Salt in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."
    • changedOutput schema / properties / products / items / properties / saturated_fat_100g / description
      Previous value: -"Saturated fat in grams per 100 g, or per 100 ml for liquids. Absent when not entered."New value: +"Saturated fat in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."
    • changedOutput schema / properties / products / items / properties / sugars_100g / description
      Previous value: -"Total sugars in grams per 100 g, or per 100 ml for liquids. Absent when not entered."New value: +"Total sugars in grams per 100 g, or per 100 ml for liquids, as sold. Absent when not entered, or when this read returned only prepared figures (see prepared)."
  4. Changed12 schema fields changed
    • changedInput schema / properties / barcodes / description
      Previous value: -"2–10 barcodes to compare, returned as one row each in input order. Example: [\"3017620422003\", \"7622210100146\"]."New value: +"Barcodes to compare, returned as one row each in input order; a repeated barcode is compared once, so two identical barcodes yield one row. One call compares at most 10 distinct barcodes: up to 100 are accepted, and those past the 10th distinct one are returned in unprocessed without being fetched. Example: [\"3017620422003\", \"7622210100146\"]."
    • changedInput schema / properties / barcodes / maxItems
      Previous value: -10New value: +100
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_error`: Open Food Facts returns a 5xx other than 501 or 504, serves an HTML error page with a 2xx or 5xx status, or is unreachable for a barcode — reported in that barcode's failed entry rather than failing the call. `upstream_timeout`: Open Food Facts did not answer a barcode within the request deadline, or answered 408, 425, or 504 — reported in that barcode's failed entry rather than failing the call. `upstream_rejected`: Open Food Facts refuses a barcode with a 4xx other than 404, 408, 425, or 429, or with 501 Not Implemented — reported in that barcode's failed entry rather than failing the call. `rate_limited`: This server's own per-minute product budget is spent, or Open Food Facts answers 429 — reported in that barcode's failed entry rather than failing the call. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_error`: Open Food Facts returns a 5xx other than 501 or 504, serves an HTML error page with a 2xx or 5xx status, answers 2xx with a malformed envelope, or is unreachable for a barcode — reported in that barcode's failed entry rather than failing the call. `upstream_timeout`: Open Food Facts did not answer a barcode within the request deadline, or answered 408, 425, or 504 — reported in that barcode's failed entry rather than failing the call. `upstream_rejected`: Open Food Facts refuses a barcode with a 4xx other than 404, 408, 425, or 429, or with 501 Not Implemented — reported in that barcode's failed entry rather than failing the call. `rate_limited`: This server's own per-minute product budget is spent, or Open Food Facts answers 429 — reported in that barcode's failed entry rather than failing the call. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / products / description
      Previous value: -"Comparison rows in input order — one per barcode whose fetch completed, whether or not a record exists. Barcodes whose fetch failed have no row here; they appear in failed."New value: +"Comparison rows in input order — one per distinct barcode whose fetch completed, whether or not a record exists. Barcodes whose fetch failed have no row here; they appear in failed. Barcodes past the cap appear in unprocessed."
    • changedOutput schema / properties / products / items / properties / energy_kcal_100g / description
      Previous value: -"Energy per 100g in kcal. Absent when not entered."New value: +"Energy in kcal per 100 g, or per 100 ml for liquids. Absent when not entered."
    • changedOutput schema / properties / products / items / properties / fat_100g / description
      Previous value: -"Total fat per 100g in grams. Absent when not entered."New value: +"Total fat in grams per 100 g, or per 100 ml for liquids. Absent when not entered."
    • changedOutput schema / properties / products / items / properties / fiber_100g / description
      Previous value: -"Dietary fiber per 100g in grams. Often absent."New value: +"Dietary fiber in grams per 100 g, or per 100 ml for liquids. Often absent."
    • changedOutput schema / properties / products / items / properties / proteins_100g / description
      Previous value: -"Protein per 100g in grams. Absent when not entered."New value: +"Protein in grams per 100 g, or per 100 ml for liquids. Absent when not entered."
    • changedOutput schema / properties / products / items / properties / salt_100g / description
      Previous value: -"Salt per 100g in grams. Absent when not entered."New value: +"Salt in grams per 100 g, or per 100 ml for liquids. Absent when not entered."
    • changedOutput schema / properties / products / items / properties / saturated_fat_100g / description
      Previous value: -"Saturated fat per 100g in grams. Absent when not entered."New value: +"Saturated fat in grams per 100 g, or per 100 ml for liquids. Absent when not entered."
    • changedOutput schema / properties / products / items / properties / sugars_100g / description
      Previous value: -"Total sugars per 100g in grams. Absent when not entered."New value: +"Total sugars in grams per 100 g, or per 100 ml for liquids. Absent when not entered."
    • addedOutput schema / properties / unprocessed
      Added value: +{
      +  "description": "Distinct barcodes past the 10th, in input order — never fetched, so nothing is known about them. Absent when the batch held 10 or fewer distinct barcodes. Compare them in another off_compare_products call (2–10 barcodes), or look a single one up with off_get_product.",
      +  "items": {
      +    "description": "Barcode left unprocessed, as provided in input.",
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
  5. Changed1 schema field changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_error`: Open Food Facts returns a 5xx other than 501, serves an HTML error page with a 2xx or 5xx status, or is unreachable — surfaced per barcode in failed[]. `upstream_timeout`: Open Food Facts did not answer within the request deadline — surfaced per barcode in failed[]. `upstream_rejected`: Open Food Facts answers 4xx or 501 Not Implemented for a barcode — surfaced per barcode in failed[]. `rate_limited`: This server's own per-minute request budget is spent, or Open Food Facts answers 429 — surfaced per barcode in failed[]. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_error`: Open Food Facts returns a 5xx other than 501 or 504, serves an HTML error page with a 2xx or 5xx status, or is unreachable for a barcode — reported in that barcode's failed entry rather than failing the call. `upstream_timeout`: Open Food Facts did not answer a barcode within the request deadline, or answered 408, 425, or 504 — reported in that barcode's failed entry rather than failing the call. `upstream_rejected`: Open Food Facts refuses a barcode with a 4xx other than 404, 408, 425, or 429, or with 501 Not Implemented — reported in that barcode's failed entry rather than failing the call. `rate_limited`: This server's own per-minute product budget is spent, or Open Food Facts answers 429 — reported in that barcode's failed entry rather than failing the call. Other values are possible when a failure originates below the handler."
  6. Changed5 schema fields changed
    • changedInput schema / properties / barcodes / items / description
      Previous value: -"EAN-13 or UPC barcode (8–14 digits)."New value: +"Product barcode, digits only: 4–40 digits after any leading zeros."
    • changedInput schema / properties / barcodes / items / pattern
      Previous value: -"^\\d{8,14}$"New value: +"^0*[1-9]\\d{3,39}$"
    • changedOutput schema / properties / failed / items / properties / barcode / description
      Previous value: -"EAN-13 or UPC barcode whose fetch failed."New value: +"Barcode whose fetch failed, as provided in input."
    • changedOutput schema / properties / not_found / items / description
      Previous value: -"EAN-13 or UPC barcode with no contributor record."New value: +"Barcode with no contributor record, as provided in input."
    • changedOutput schema / properties / products / items / properties / barcode / description
      Previous value: -"EAN-13 or UPC barcode (same as provided input)."New value: +"Barcode, echoed exactly as provided in input."
  7. Changed3 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_error`: Open Food Facts returns 5xx, serves an HTML error page, or is unreachable — surfaced per barcode in failed[] `upstream_timeout`: Open Food Facts did not answer within the request deadline — surfaced per barcode in failed[] `upstream_rejected`: Open Food Facts answers 4xx for a barcode — surfaced per barcode in failed[] `rate_limited`: This server's own per-minute request budget is spent, or Open Food Facts answers 429 — surfaced per barcode in failed[] Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_error`: Open Food Facts returns a 5xx other than 501, serves an HTML error page with a 2xx or 5xx status, or is unreachable — surfaced per barcode in failed[]. `upstream_timeout`: Open Food Facts did not answer within the request deadline — surfaced per barcode in failed[]. `upstream_rejected`: Open Food Facts answers 4xx or 501 Not Implemented for a barcode — surfaced per barcode in failed[]. `rate_limited`: This server's own per-minute request budget is spent, or Open Food Facts answers 429 — surfaced per barcode in failed[]. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / products / items / properties / ecoscore_grade / description
      Previous value: -"Green-Score/Eco-Score (a–e or \"unknown\"). Often absent."New value: +"Green-Score (formerly Eco-Score) environmental impact grade: \"a-plus\" (lowest impact), then \"a\" through \"f\"; \"unknown\" when the data it needs is missing, or \"not-applicable\" for product categories the score does not cover. Often absent."
    • changedOutput schema / properties / products / items / properties / nutriscore_grade / description
      Previous value: -"Nutri-Score letter (a–e). Absent when not computed."New value: +"Nutri-Score grade: \"a\" through \"e\", \"unknown\" when the nutrition data entered is not enough to compute it, or \"not-applicable\" for product categories the score does not cover. Absent when Open Food Facts sent none."
  8. 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": [
      +      "products",
      +      "succeeded",
      +      "not_found"
      +    ]
      +  },
      +  {
      +    "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: `upstream_error`: Open Food Facts returns 5xx, serves an HTML error page, or is unreachable — surfaced per barcode in failed[] `upstream_timeout`: Open Food Facts did not answer within the request deadline — surfaced per barcode in failed[] `upstream_rejected`: Open Food Facts answers 4xx for a barcode — surfaced per barcode in failed[] `rate_limited`: This server's own per-minute request budget is spent, or Open Food Facts answers 429 — surfaced per barcode in failed[] Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "upstream_error",
      +            "upstream_timeout",
      +            "upstream_rejected",
      +            "rate_limited"
      +          ],
      +          "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: -[
      -  "products",
      -  "succeeded",
      -  "not_found"
      -]
  9. Changed3 schema fields changed
    • addedOutput schema / properties / failed
      Added value: +{
      +  "description": "Barcodes whose fetch failed, with the per-barcode reason. Absent when every fetch completed. A barcode listed here is unknown, not absent from Open Food Facts — retry it with off_get_product before concluding anything about the product.",
      +  "items": {
      +    "additionalProperties": false,
      +    "description": "A single barcode whose fetch failed.",
      +    "properties": {
      +      "barcode": {
      +        "description": "EAN-13 or UPC barcode whose fetch failed.",
      +        "type": "string"
      +      },
      +      "error": {
      +        "description": "What went wrong for this barcode and what to do about it.",
      +        "type": "string"
      +      },
      +      "reason": {
      +        "description": "Declared failure reason — one of upstream_error, upstream_timeout, upstream_rejected, rate_limited.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "barcode",
      +      "reason",
      +      "error"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / not_found / description
      Previous value: -"Barcodes with no contributor record. Not an error — the product may exist but not yet entered in Open Food Facts."New value: +"Barcodes Open Food Facts answered for, confirming no contributor record exists. Not an error — the product may exist but not yet be entered. Never used for a fetch that failed."
    • changedOutput schema / properties / products / description
      Previous value: -"Comparison rows, one per barcode in input order."New value: +"Comparison rows in input order — one per barcode whose fetch completed, whether or not a record exists. Barcodes whose fetch failed have no row here; they appear in failed."
  10. Changed1 schema field changed
    • changedInput schema / properties / barcodes / description
      Previous value: -"2–10 barcodes to compare. All products are fetched in parallel. Example: [\"3017620422003\", \"7622210100146\"]."New value: +"2–10 barcodes to compare, returned as one row each in input order. Example: [\"3017620422003\", \"7622210100146\"]."
  11. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations cover only the safety profile (readOnly/idempotent/openWorld), and the description goes well beyond them: dedup of repeated barcodes, the 10-distinct cap routing extras to unprocessed, partial-batch semantics (not_found vs. failed are separated), no imputation of missing nutrition, regional score-formula caveats, and ODbL citation duty. The as-sold vs. prepared re-read behavior is a genuinely non-obvious trait that an agent could not get from the schema or annotations.

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?

Front-loaded and information-dense, with no filler sentences, but the prepared/as-sold sentence is a run-on that takes several re-reads to parse ('one more product read, of the as-sold set its record stores, once the read of every barcode has settled'). Everything earns its place, yet the packaging obscures it; splitting that clause would help considerably.

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

Completeness4/5

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

For a batch tool with a rich output surface, the description covers failure modes, dedup, unit basis, and licensing — enough for correct invocation. Since an output schema exists, the heavy explanation of row structure and prepared/stored_as_sold fields is partly redundant, but that is over-delivery rather than a gap.

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 barcode pattern, minItems/maxItems and dedup rule are already documented. The description still adds interpretive value by tying the cap to downstream behavior (extras land in unprocessed 'rather than fetched') and reinforcing input-order rows, but it restates more than it extends on the single parameter.

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?

Opens with a specific verb+resource+scope: 'Side-by-side nutrition and scoring comparison for 2–10 products per call by barcode.' An agent can immediately distinguish this from off_get_product (single product) and off_search_products (discovery), and the comparison framing plus the named metrics make the output contract obvious.

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?

Gives concrete use-case framings ('which of these cereals is healthiest?', 'compare these pasta brands'), which clearly implies when to reach for this over single-product reads. It never explicitly names off_get_product as the fallback for one barcode, so the alternative route is left to inference rather than 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.