Skip to main content
Glama

openfoodfacts-mcp-server

by io.github.cyanheads

Search Food Products

off_search_products
Read-onlyIdempotent

Search Open Food Facts by full-text query, structured tag filters, or both at once. Returns a summary list with barcodes, product names, brands, Nutri-Score, NOVA group, and categories — enough for triage and selection, not full label data. Use off_get_product on the returned barcodes for complete details. A text query and tag filters combine: results match the query text and satisfy every filter provided (e.g. query "dark chocolate" with labels_tag "en:organic" and countries_tag "en:france" returns organic chocolate sold in France); additives_tag is the one exception, filtering only on searches with no text query. Tag filter values must be canonical tag IDs (e.g. "en:organic", "en:gluten-free") — use off_browse_taxonomy to resolve human terms to tag IDs. At least one search parameter is required. Data is crowd-sourced; result count reflects contributed products, not all products in the market. Data under ODbL 1.0 — cite Open Food Facts in downstream use.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageNoPage number (1-based). Use with page_size to paginate results. Searches that include a text query serve only the first 10,000 results, so page * page_size must stay at or below 10,000 — a deeper request is rejected rather than sent. Tag-only searches have no published window, but Open Food Facts refuses deep pages unpredictably; narrowing the filters is more reliable than paging far in.
queryNoFull-text search term across product names, brands, and ingredients. Combines with any tag filters — results match this text and satisfy the filters. Example: "dark chocolate 70%".
sort_byNoSort order for searches without a text query. "unique_scans_n" surfaces the most-scanned products; omitting returns results in default order. Searches that include a text query are relevance-ranked and ignore this option.
page_sizeNoResults per page (1–50, default 20). Keep low for initial exploration; increase for comparison workflows.
brands_tagNoBrand slug (lowercased, hyphenated). Example: "nutella", "kelloggs". Matched exactly against the normalized slug — a partial or misspelled slug matches nothing rather than falling back to a near match, so put open-ended brand wording in query instead.
labels_tagNoCanonical label/certification tag ID. Example: "en:organic", "en:fair-trade", "en:no-gluten". Use off_browse_taxonomy with facet="labels".
nova_groupNoFilter by NOVA food processing class. "1"=unprocessed/minimally processed, "4"=ultra-processed. Products without a NOVA score are excluded.
additives_tagNoCanonical additive (E-number) tag ID. Example: "en:e322", "en:e330". Use off_browse_taxonomy with facet="additives". Available only on searches with no query — full-text searches cannot filter by additive, so combining the two is rejected instead of silently returning nothing.
allergens_tagNoCanonical allergen tag ID. Example: "en:milk", "en:gluten". Use off_browse_taxonomy with facet="allergens". Selects products that declare this allergen; it cannot select allergen-free products, because a product with no allergen tags may simply have none entered yet.
countries_tagNoCanonical country tag ID. Example: "en:france", "en:united-states". Filters to products sold in that country.
categories_tagNoCanonical category tag ID. Example: "en:breakfast-cereals", "en:cheeses". Use off_browse_taxonomy with facet="categories" to discover valid values.
nutrition_gradeNoFilter by Nutri-Score grade. "a" is highest nutritional quality, "e" is lowest. Products without a score are excluded.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe page_size that was applied.
pageNoCurrent page number (1-based).
errorNoPresent when the call failed. Absent on success.
shownNoNumber of products returned on this page.
totalNoMatching products in the database for this search. Exact unless total_is_lower_bound is true, in which case at least this many match and the real figure is unknown.
noticeNoGuidance about this result set — echoes the filters and suggests how to broaden when nothing matched, or names the current page and how far the backend will actually paginate when more results exist.
productsNoMatching products. Use barcodes with off_get_product for full label data.
truncatedNoTrue when more results exist beyond this page.
page_countNoProducts returned on this page (mirrors page_size except on the last page). Not the total number of pages.
total_is_lower_boundNoTrue when the backend stopped counting at its ceiling and total is a floor, not the match total. Only text searches can hit it; add filters to bring the result set under the ceiling and get an exact count.

TDQS

A5/5.0
Behavior5/5

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

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds significant behavioral nuance: exact slug matching for brands (no fallback), page limit with text queries, unpredictable deep paging on tag-only searches, additives_tag only valid without query, allergens_tag unable to select allergen-free products, and licensing obligations (ODbL 1.0). These go well beyond the annotations and make the tool's quirks explicit.

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

Conciseness5/5

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

The description is long (over 250 words) but every sentence earns its place given the tool's 12 parameters and numerous edge cases. It is front-loaded with the core purpose, then logically organizes combination semantics, tag ID requirements, constraints, and data caveats. No filler or tautology — each clause addresses a specific agent need.

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 12 parameters, no required fields, an output schema, and multiple edge cases (page limits, additive exception, exact match behavior, allergen semantics), the description covers every important aspect an agent needs to call it correctly. It even anticipates failure modes (rejected deep pages) and data quality implications. The output schema exists, so the return format summary is sufficient.

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

Parameters5/5

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

Although schema coverage is 100%, the description adds cross-parameter semantics that the schema alone cannot: how query and tag filters combine (including the additive exception), the 10,000-result window interplay between page/page_size and query, the exact-match risk for brands_tag, and the meaning of sort_by being ignored when a query is present. It also provides examples for tag IDs and usage guidance for several filters.

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 description states a precise verb+resource ('Search Open Food Facts') and distinguishes it from siblings by naming off_get_product for full details and off_browse_taxonomy for tag resolution. It clearly communicates the tool's scope (summary list for triage) and the three modes (query, filters, both).

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?

The description explicitly tells when to use this tool vs alternatives ('Use off_get_product on the returned barcodes for complete details', 'use off_browse_taxonomy to resolve human terms to tag IDs'). It explains the combination semantics with a concrete example, the additive exception, the requirement of at least one parameter, and the crowd-sourced data caveat — all governing correct usage.

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

All openfoodfacts-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: taxonomy resolution, product search, product details, and comparative analysis. No overlap or ambiguity exists between them.

Naming Consistency5/5

All tools follow a consistent 'off_verb_noun' pattern with snake_case (browse_taxonomy, compare_products, get_product, search_products). The naming is predictable and immediately conveys the action and target.

Tool Count5/5

With only 4 tools, the server stays well-scoped and avoids redundancy. This is an ideal size for a focused read-only API covering search, fetch, compare, and taxonomy lookup.

Completeness5/5

For a read-only crowd-sourced database, the toolset covers all essential workflows: discovering products (search), retrieving full details (get), comparing alternatives (compare), and resolving filter values (browse_taxonomy). No critical gaps are apparent.

Resources