Enables developers to query Open Food Facts data, perform product analysis, and retrieve food information directly within VS Code via GitHub Copilot.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Open Food Facts MCP Server compare Cheerios and Frosted Flakes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This is a Model Context Protocol (MCP) server implementation for Open Food Facts. It enables AI assistants to access food product information, providing nutritional analysis, product comparisons, and recipe suggestions using the official Model Context Protocol specification.
This MCP server enables:
Nutritional Intelligence: Get AI-powered analysis of food products and their health implications
Informed Choices: Compare products to make better dietary decisions
Recipe Ideas: Discover recipes based on products you have
Dietary Support: Understand allergens, additives, and dietary compatibility
searchProducts: Search for products in the Open Food Facts database by name, brand, category, or other keywords
getProductByBarcode: Get detailed information about a product by its barcode (EAN, UPC, etc.)
analyzeProduct: Get AI-powered nutritional analysis of a food product
compareProducts: Compare two products with AI-powered insights
suggestRecipes: Get AI-powered recipe suggestions using a product
searchByCategory: Search products within a specific food category (e.g., beverages, snacks, dairy, cereals)
searchByBrand: Find all products from a specific brand
advancedSearch: Advanced product search with multiple filters including category, brand, Nutri-Score, Eco-Score, NOVA group, allergen-free options, labels, and country
autocomplete: Get autocomplete suggestions for categories, brands, labels, ingredients, allergens, or additives
getNutriScore: Get the Nutri-Score grade (A-E) for a product - quick health assessment at a glance
getEcoScore: Get the Eco-Score (environmental impact rating A-E) for a product
getAdditivesInfo: List all additives in a product with their E-numbers and NOVA processing level
getAllergenCheck: Check if a product contains a specific allergen (gluten, milk, eggs, nuts, peanuts, soy, fish, shellfish, etc.)
checkMultipleAllergens: Check if a product contains any of multiple allergens at once
getProductAIQuestions: Get AI-generated questions about a product that need human verification
getRandomAIQuestions: Get random AI-generated questions from Robotoff that need human verification - great for community contribution
getProductInsights: Get AI-generated insights about products (detected labels, categories, ingredients issues, etc.)
getInsightTypes: Get a summary of available AI insight types in Robotoff
getProductPrices: Get price history and current prices for a product from Open Prices
searchPrices: Search for prices with filters (currency, country, date range)
getRecentPrices: Get recently added prices to discover what's available
Related MCP server: Open Food Facts MCP Server
Node.js (v16.x or higher)
npm or yarn
Clone or download this repository
Install dependencies:
npm installBuild the server:
npm run buildStart the server:
npm startStart the MCP server:
npm startAdd to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"openfoodfacts": {
"command": "node",
"args": ["/path/to/OpenFoodFacts-MCP/dist/index.js"],
"env": {
"TRANSPORT": "stdio"
}
}
}
}Install the "Model Context Protocol" extension for VS Code
Create .vscode/mcp.json:
{
"servers": {
"openfoodfacts": {
"command": "node",
"args": ["${workspaceFolder}/dist/cli.js"],
"env": {
"TRANSPORT": "stdio"
}
}
}
}The server supports HTTP/SSE transport for browser-based AI tools:
TRANSPORT=http PORT=3000 npm startThen connect your AI tool to http://localhost:3000/sse
Here are natural ways to ask your AI assistant to use the Open Food Facts tools:
"Search for chocolate cereals in the Open Food Facts database"
"Find products that contain almond milk"
"Look for organic yogurt products"
"Get information about the product with barcode 3017620422003"
"What's in the product with EAN 5000159407236?"
"Show me nutritional data for barcode 8076809513326"
"Can you analyze Nutella nutritionally?"
"Analyze Cheerios cereal and tell me if it's healthy"
"Give me a health analysis of Oreo cookies"
"Is the product with barcode 3017620422003 healthy?"
"Compare Nutella and Nocciolata"
"Which is healthier: Coke or Pepsi?"
"Compare almond milk and soy milk nutritionally"
"Compare the products with barcodes 3017620422003 and 5000159407236"
"What can I make with Greek yogurt?"
"Suggest some recipes using chickpeas"
"Give me recipe ideas for quinoa"
"What recipes can I make with the product 3017620422003?"
"Show me all products in the beverages category"
"Find all Nestlé products"
"Search for organic products with Nutri-Score A"
"Find vegan snacks with good Eco-Score"
"Does Nutella contain gluten?"
"Check if this product is safe for someone allergic to milk and eggs"
"Is barcode 3017620422003 peanut-free?"
"What allergens are in Cheerios?"
"What's the current price of Nutella?"
"Show me recent prices for products in France"
"Compare prices for barcode 3017620422003"
The MCP server provides helpful resources and prompts:
The server provides educational resources to help you understand food data:
Quick Help Guide: How to use the Open Food Facts tools - quick reference
Nutri-Score Guide: Understanding Nutri-Score health ratings (A-E)
Eco-Score Guide: Understanding Eco-Score environmental ratings (A-E)
Allergens Reference: Common food allergens and where they hide
Food Additives Guide: Understanding E-numbers and food additives
NOVA Processing Guide: Understanding food processing levels (1-4)
Pre-configured prompts help you get started quickly:
analyze-product: Get detailed nutritional analysis
compare-products: Compare two products side-by-side
find-healthy-alternatives: Find healthier alternatives to a product
check-allergens: Check if a product is safe for your allergies
whats-for-dinner: Get recipe ideas using a product
The MCP server acts as a bridge between AI assistants and the Open Food Facts database:
Your Question: You ask your AI assistant about food products
Tool Detection: The AI recognizes it needs Open Food Facts data
MCP Request: The AI calls the appropriate MCP tool
Data Retrieval: The server fetches data from Open Food Facts
AI Analysis: The AI processes the data and responds to you
You: "Is Nutella healthy?"
AI Assistant uses:
1. searchProducts to find Nutella
2. getProductByBarcode with the barcode
3. analyzeProduct for nutritional assessment
Response: Detailed analysis of Nutella's nutritional profile,
health scores, ingredients, and dietary considerationsYou: "Which is better for me, Nutella or almond butter?"
AI Assistant uses:
1. searchProducts for both products
2. compareProducts with both barcodes
Response: Side-by-side comparison with recommendations
based on your dietary needsYou: "What can I make with Greek yogurt?"
AI Assistant uses:
1. searchProducts to find Greek yogurt
2. suggestRecipes with the product
Response: Recipe suggestions that use Greek yogurt
as an ingredientThe server follows a modular architecture for maintainability and scalability:
Core Server
src/index.ts: Entry point
src/server.ts: Core MCP server implementation with resource and prompt registration
src/cli.ts: CLI interface for development
Tools (Modular Design)
src/tools/index.ts: Tool registration orchestrator and core product tools
src/tools/product-search.ts: Product search and barcode lookup utilities
src/tools/category-tools.ts: Category and brand search tools
src/tools/nutrition-tools.ts: Nutrition scores, allergen checks, and additive information
src/tools/insights-tools.ts: AI-generated insights from Robotoff
src/tools/price-tools.ts: Product pricing data from Open Prices
src/tools/types.ts: Shared type definitions and interfaces
src/tools/helpers.ts: Reusable helper functions for all tools
Resources & Services
src/resources/: Resource handlers for guides and documentation
resource-registry.ts: Resource registration system
static-resources.ts: Static resource content (guides, references)
src/sampling/: AI model integration for analysis and recipe generation
sampling-service.ts: MCP sampling integration for AI-powered features
Infrastructure
src/transport/: Communication layer (stdio for CLI/editors, HTTP for browsers)
src/config/: Server configuration
All product data comes from Open Food Facts, a free, open, collaborative database of food products from around the world.
Ensure Node.js v16+ is installed
Run npm install to install dependencies
Check that port 3000 is available (for HTTP mode)
Verify the MCP server is running
Check your AI assistant's MCP configuration
Ensure the transport type matches (stdio vs HTTP)
Try searching first with searchProducts
Verify the barcode is correct (8-14 digits)
Some products may not be in the database yet
The server fetches real-time data from Open Food Facts
First requests may be slower as data is retrieved
Internet connection speed affects performance
We welcome contributions! You can help by:
Adding support for more food databases
Improving AI analysis prompts
Enhancing error handling
Adding new tools for dietary tracking
Improving documentation
Open Food Facts is a food products database made by everyone, for everyone. It's a collaborative project that collects information about food products from around the world, including:
Ingredients
Nutritional facts
Allergens
Environmental impact
Health scores (Nutri-Score, NOVA)
Learn more at https://world.openfoodfacts.org/
This project is licensed under the GNU Affero General Public License v3.0, consistent with the Open Food Facts project.
Open Food Facts Website: https://world.openfoodfacts.org/
Open Food Facts GitHub: https://github.com/openfoodfacts
Model Context Protocol: https://modelcontextprotocol.io/
Made with care for food-aware consumers everywhere
Advanced product search with multiple filters: category, brand, nutri-score, eco-score, NOVA group, allergen-free, labels, country
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query (product name, ingredients, etc.) | |
| category | No | Filter by category | |
| brand | No | Filter by brand | |
| nutriscoreGrade | No | Filter by Nutri-Score grade | |
| ecoscoreGrade | No | Filter by Eco-Score grade | |
| novaGroup | No | Filter by NOVA group (food processing level) | |
| allergenFree | No | Filter by allergen-free (e.g., "gluten", "milk", "eggs") | |
| labels | No | Filter by labels (e.g., "organic", "fair-trade", "vegan") | |
| countries | No | Filter by country (e.g., "united-states", "france") | |
| sortBy | No | ||
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether the operation is read-only, pagination behavior, or any side effects, leaving the agent uninformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently lists the key filters, but could be slightly more structured to improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters and no output schema or annotations, the description is too minimal; it omits details on result format, pagination, and usage hints for a complex search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (75%), and the description merely lists filter names without adding extra meaning beyond the schema's own parameter descriptions, offering marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is an advanced product search with multiple filters listed, distinguishing it from simpler search siblings like searchByBrand or searchByCategory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when multiple filters are needed, but lacks explicit guidance on when not to use it or alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get AI nutritional analysis of a product
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrBarcode | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description fails to disclose any behavioral traits such as data sources, analysis scope, or limitations, leaving the agent uninformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (9 words), which is concise but under-specified; it lacks structure such as front-loading critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the domain (product analysis) and the presence of many sibling tools, the description is far too minimal to provide completeness, especially without output schema or parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'nameOrBarcode' is not described beyond its name; with 0% schema description coverage, the description adds no meaning to aid parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and a distinct resource 'AI nutritional analysis of a product', clearly distinguishing it from siblings like 'getNutriScore' or 'getProductByBarcode'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'getNutriScore' or 'compareProducts'; no context or exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get autocomplete suggestions for categories, brands, labels, ingredients, allergens, or additives
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Autocomplete query | |
| taxonomyType | Yes | Type of taxonomy to search | |
| lang | No | Language code | en |
| limit | No | Maximum number of suggestions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It only states it 'gets suggestions' but does not disclose matching behavior (exact/partial), case sensitivity, response format, or any side effects. For a tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with 14 words. Every word adds value, and the structure is front-loaded with the tool's purpose. No superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no behavioral context, the description is incomplete. It does not explain what the suggestions look like (e.g., list of strings?), how results are ordered, or any limitations (e.g., max suggestions beyond limit parameter). Given the tool has 4 parameters and is a retrieval operation, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes each parameter. The description adds no additional meaning beyond what the schema provides (e.g., no explanation of query formatting or taxonomyType implications). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns autocomplete suggestions for specific taxonomies (categories, brands, etc.). The verb 'Get' and resource 'autocomplete suggestions' are well-defined. It distinguishes from sibling tools like advancedSearch, which perform full searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies it's for quick suggestions while typing, but does not exclude when to use sibling tools (e.g., searchProducts for full results). Usage context is implied, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if a product contains any of multiple allergens at once
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrBarcode | Yes | Product name or barcode | |
| allergens | Yes | List of allergens to check (e.g., ["gluten", "milk", "eggs"]) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only provides a vague 'check if contains' without specifying return type, effects, or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, lacks structural elements like bullet points or separation of concerns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description fails to explain return format or success/error conditions. Behavioral details are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parametric details are already covered. The description adds no meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks if a product contains any of multiple allergens, which is specific and distinguishable from sibling getAllergenCheck that likely handles single allergens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The distinction from getAllergenCheck for single allergen checking is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two products using AI
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrBarcode1 | Yes | ||
| nameOrBarcode2 | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Lacks annotations; 'using AI' is vague. No disclosure of return format, performance, or side effects. Provides minimal insight into how the comparison works.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single short sentence is concise but lacks essential details. It is not verbose, but underspecification reduces efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For two parameters, no output schema, and no annotations, the description is too sparse. It does not explain what the comparison returns or how results are structured, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameters 'nameOrBarcode1' and 'nameOrBarcode2' are named suggestively but no description explains accepted formats (e.g., product name, barcode number, or both). Schema coverage is 0%, requiring compensation from description which is absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'compare' and resource 'two products' using AI. It distinguishes from sibling tools like analyzeProduct which is single-product analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use compareProducts versus sibling tools like analyzeProduct, searchProducts, or getProductByBarcode. No when-not or alternatives provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all additives in a product with their E-numbers and NOVA processing level
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrBarcode | Yes | Product name or barcode (EAN/UPC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the return content (E-numbers, NOVA level) but does not explicitly state that the operation is read-only, nor does it mention any dependencies, rate limits, or error conditions. The behavior is implied but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 13 words, front-loading the action ('List all additives') and providing key specifics immediately. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no nested objects, no output schema), the description adequately conveys the return structure as a list of additives with E-numbers and NOVA level. It is nearly complete for the agent to understand the output, though it could be slightly improved by noting if the list is flat or grouped.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'nameOrBarcode'. The tool description restates the parameter's purpose indirectly by saying 'in a product', but adds no new semantic detail beyond the schema's own description. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and clearly identifies the resource 'additives in a product' with specific details (E-numbers, NOVA processing level). It distinguishes from sibling tools like getProductByBarcode which returns general product info, and analyzeProduct which provides broader analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need additive information) but provides no explicit guidance about when to avoid it or which sibling alternatives might be better. Given many sibling tools, explicit exclusion or alternative suggestions are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if a product contains a specific allergen (gluten, milk, eggs, nuts, peanuts, soy, fish, shellfish, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrBarcode | Yes | Product name or barcode | |
| allergen | Yes | Allergen to check for (e.g., "gluten", "milk", "eggs", "nuts", "peanuts", "soy", "fish", "shellfish") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It says 'Check if' but does not indicate the return type (e.g., boolean, detailed info) or behavior on missing data. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence listing examples, no fluff. Efficient but could benefit from additional structure (e.g., return type).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema, the description is adequate but lacks behavioral details (e.g., return value). It covers the basic purpose and parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions. The description adds useful examples for the allergen param, but no extra insight beyond schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states the tool checks for a specific allergen in a product, with a clear list of examples. It distinguishes from sibling tools like checkMultipleAllergens and analyzeProduct by focusing on a single allergen check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. The purpose implies it's for single allergen checks, but does not mention alternatives like checkMultipleAllergens for multiple allergens.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Eco-Score (environmental impact rating A-E) for a product
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrBarcode | Yes | Product name or barcode (EAN/UPC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the basic function, omitting details like data source, error conditions, or read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is concise and front-loaded, but could be expanded slightly without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is minimally adequate but lacks details on edge cases or return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% as the only parameter has a description. The tool description adds no extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the Eco-Score (environmental impact rating A-E) for a product. The verb 'Get' and specific resource 'Eco-Score' make the purpose unambiguous, and it distinguishes from sibling tools like getNutriScore.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., getNutriScore, advancedSearch). There are no conditions, prerequisites, or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a summary of available AI insight types in Robotoff
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It describes a read-only operation ('Get a summary') and does not mention side effects, authentication, or rate limits, but given the simplicity of a parameterless read call, the implied behavior is straightforward.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words. Every word adds value, and it is front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description provides the basic idea. However, it could be enhanced by briefly explaining what 'summary' means (e.g., list of type names and descriptions) or how the result can be used. The simplicity of the tool partially justifies the brevity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the schema coverage is 100% (trivially). The description does not need to add parameter details since there are none. The baseline for zero-parameter tools is 4, indicating adequate clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Get' and specifies the resource 'summary of available AI insight types in Robotoff', which clearly indicates the tool's purpose. It distinguishes from sibling tools like getProductInsights or getProductAIQuestions that focus on specific products or questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like getProductInsights or getRandomAIQuestions. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Nutri-Score grade (A-E) for a product - quick health assessment at a glance
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrBarcode | Yes | Product name or barcode (EAN/UPC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fails to disclose any behavioral traits such as read-only nature, external API calls, error handling, or response format. It only gives a vague 'quick health assessment' without specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste, but it is too terse and misses critical information about usage and behavior, making it less effective than it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description lacks details on return values, error conditions, and real-world behavior, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter nameOrBarcode described. The description adds context ('quick health assessment') but does not elaborate on parameter format or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Get the Nutri-Score grade (A-E) for a product', which is a specific verb-resource combination. It distinguishes from sibling tools like getEcoScore and getProductByBarcode by focusing on Nutri-Score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives like getEcoScore or searchProducts. No when-not or alternative conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get AI-generated questions about a product that need human verification (e.g., "Is this product organic?", "Does this contain gluten?")
| Name | Required | Description | Default |
|---|---|---|---|
| barcode | Yes | Product barcode (EAN/UPC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states purpose and examples. Does not disclose read-only nature, return format, or any side effects. Adequate but minimal for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with examples, front-loaded, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output format or behavior description, but given no output schema and simple input, it is mostly complete. Could benefit from mentioning response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'barcode' with schema description already present. Description adds examples of questions but no additional parameter details. Schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool retrieves AI-generated questions about a product that require human verification, with concrete examples. Distinguishes itself from siblings like getRandomAIQuestions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for product-specific AI questions needing verification, but no explicit when-to-use or when-not-to-use guidance nor alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get product details by barcode (EAN/UPC)
| Name | Required | Description | Default |
|---|---|---|---|
| barcode | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It states 'Get product details' implying a read operation, but omits details like what specific fields are returned, potential rate limits, authentication requirements, or data source freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no extraneous words. It is front-loaded and efficient, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with one parameter and no output schema, the description is adequate. However, adding context about the return value (e.g., 'including name, brand, and nutrition') would improve completeness without being verbose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the barcode parameter. The description adds meaning by specifying the barcode format (EAN/UPC), which helps an agent know what to input. However, it does not include examples or validation rules, so it's not a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get product details by barcode (EAN/UPC)' clearly states the action (get), the resource (product details), and the specific identifier (barcode with formats EAN/UPC). It distinguishes from siblings like searchProducts which search by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a barcode, but provides no explicit guidance on when not to use it (e.g., for non-barcode queries) or alternatives. Siblings like searchProducts exist, but no comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get AI-generated insights about products (detected labels, categories, ingredients issues, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| barcode | No | Filter by product barcode | |
| insightType | No | Type of insight to retrieve | |
| country | No | Filter by country | |
| count | No | Number of insights to return | |
| page | No | Page number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It implies a read operation ('Get') but does not explicitly state it is read-only, idempotent, or free of side effects. No mention of rate limits, caching, or potential error conditions. Insufficient for an agent to understand behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with the core purpose, followed by parenthetical examples. Every word earns its place. No unnecessary qualifiers or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 5 optional parameters, no output schema, and no annotations, the description is minimal. It does not clarify how parameters interact (e.g., whether barcode is needed for insights), pagination behavior, or return format. The examples are helpful but incomplete for an agent to use effectively without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 5 parameters with descriptions (100% coverage). The description adds value by contextualizing the insightType enum with examples like 'detected labels, categories, ingredients issues', which helps the agent understand the type of data returned. This goes beyond the enum labels.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves AI-generated insights about products with specific examples like labels, categories, ingredients issues. It identifies the resource (products) and action (get insights). However, it does not explicitly distinguish it from similar tools like getNutriScore or getEcoScore, which are more specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or when not to use it. The description only states what it does, not when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get crowd-sourced price data for a specific product - see where it costs less
| Name | Required | Description | Default |
|---|---|---|---|
| barcode | Yes | Product barcode to get prices for | |
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the action (get price data) but does not mention read-only nature, authentication needs, rate limits, or error handling when barcode is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence), but given the tool has three parameters and no output schema, it is too brief to be fully effective. It earns its place but leaves out critical details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a tool with three parameters and no output schema. It does not explain how pagination works, what the return format is, or when this tool is preferable over sibling price tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 33% of parameters have schema descriptions (barcode only). The tool description adds no additional meaning to page or pageSize, and the schema coverage is low, so the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves crowd-sourced price data for a product and hints at comparative pricing, which distinguishes it from product info tools like getProductByBarcode. However, it does not explicitly differentiate from other price-related siblings like getRecentPrices or searchPrices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description lacks context for selection, such as when to use getProductPrices over getRecentPrices or compareProducts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get random AI-generated questions from Robotoff that need human verification - great for community contribution
| Name | Required | Description | Default |
|---|---|---|---|
| barcode | No | Filter by product barcode | |
| insightType | No | Type of question to retrieve | |
| lang | No | Language for questions | en |
| count | No | Number of questions to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool retrieves questions needing verification, suggesting a read-only operation, but does not explicitly confirm non-destructive behavior, rate limits, or behavior when no questions are available. Minimal disclosure beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it very concise. It front-loads the core action effectively. It could be improved by structuring the use-case hint ('great for community contribution') more prominently, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (random retrieval) with optional parameters and no output schema. The description covers the basic purpose but lacks details on return format, error handling, and pagination. It is adequate for a minimal tool but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all four parameters (barcode, insightType, lang, count). The tool description adds no additional parameter information, so baseline score of 3 is appropriate. No extra semantics are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get random AI-generated questions from Robotoff that need human verification'. It specifies the resource (Robotoff questions) and the selection method (random). However, it does not explicitly differentiate from sibling tools like getProductAIQuestions, though the name implies a distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'great for community contribution' implies a use case, but there is no explicit guidance on when to use this tool versus alternatives (e.g., getProductAIQuestions for specific products). No when-not-to-use or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the most recently added price data from the community
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'get' without disclosing behavioral traits like pagination limits, ordering (presumably newest first), or data freshness. The description is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and concise. Every word is necessary, with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two optional params and no output schema. The description covers the basic purpose but lacks details on pagination behavior, ordering, or return format, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention page or pageSize. These parameters are common but not explained, failing to add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the most recently added price data from the community. This distinguishes it from siblings like getProductPrices (by product) and searchPrices (with filters). However, it does not explicitly differentiate from all siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It is implied for retrieving recent prices, but no context on exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all products from a specific brand
| Name | Required | Description | Default |
|---|---|---|---|
| brand | Yes | Brand name to search for | |
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states 'all products' but the pagination parameters (page, pageSize) suggest results are paged, not all at once. No mention of whether the operation is read-only, idempotent, or has side effects. This lack of transparency is misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler words. It is front-loaded with key information (action and scope).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, no output schema, no annotations), the description is severely lacking. It does not explain return format, pagination behavior, or any constraints. The agent would be unable to correctly invoke or interpret results from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (brand parameter has a description in schema). The tool description adds no additional meaning to parameters; it merely restates 'from a specific brand'. The page and pageSize parameters are completely undescribed in both schema and description, failing to inform the agent about their purpose or defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Find all products from a specific brand' clearly states the action (find) and resource (products filtered by brand). It implicitly distinguishes from sibling tools like searchByCategory or searchProducts by narrowing to brand. However, it does not explicitly differentiate from tools like advancedSearch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., searchProducts, advancedSearch). No context about optimal scenarios or when to avoid this tool is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search products within a specific food category (e.g., beverages, snacks, dairy, cereals)
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | Food category (e.g., "beverages", "snacks", "dairy", "organic") | |
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to disclose pagination behavior, result limits, or matching criteria beyond the category name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Short and to the point, but overly minimalistic; could be structured with bullet points or additional details without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple search tool, but lacks information on response format, pagination details, or how categories are matched, especially given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only repeats the category parameter examples from the schema; does not explain page or pageSize parameters despite low schema coverage (33%).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches products by food category with examples, but it does not differentiate from sibling tools like searchByBrand or searchProducts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; lacks any 'when to use' or 'when not to use' context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for crowd-sourced price data with filters (barcode, currency, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| barcode | No | Filter by product barcode | |
| currency | No | Filter by currency | |
| country | No | Filter by country | |
| orderBy | No | Order by field (e.g., "-date" for newest first) | |
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It only states that the tool searches with filters, but fails to mention pagination, sorting behavior, rate limits, or what happens with no results. This is insufficient for a search tool with multiple parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the key action and resource. It avoids unnecessary words, but could be slightly expanded with useful context without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters with pagination and no output schema, the description is too sparse. It does not explain the meaning of pagination parameters, the default ordering, or the structure of results. The presence of sibling tools like 'searchProducts' and 'getProductPrices' suggests this tool is specialized, but the description fails to clarify its niche.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter schema covers 4 out of 6 parameters (67%) with descriptions, but the tool's description adds no new meaning beyond listing example filters, which is redundant with the schema. For the two parameters without schema descriptions (page, pageSize), the description offers no clarification, so it does not compensate for the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for price data with filters, mentioning examples like barcode and currency. It is specific about the resource (crowd-sourced price data) and the action (search with filters), which helps differentiate it from sibling tools like getProductPrices or getRecentPrices, though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like advancedSearch or searchProducts. It does not specify prerequisites, exclusion criteria, or typical use cases, leaving the agent to infer usage solely from the name and filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search products by name, brand, or category
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| page | No | ||
| pageSize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the search purpose without mentioning pagination behavior, authentication needs, or result limitations. This is inadequate for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at 6 words, but it misses critical information like pagination and parameter details. While not verbose, it is under-specified, which reduces its effectiveness for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and many sibling tools, the description is incomplete. It fails to explain how it differs from other search tools, does not describe the return format, and omits pagination behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should add meaning beyond parameter names. It mentions query by name/brand/category but ignores page and pageSize parameters, which are not self-explanatory in terms of their purpose and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches products by name, brand, or category, providing a specific verb and resource. However, it does not differentiate from sibling tools like searchByBrand or searchByCategory, which are more targeted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. With 20 sibling tools including advancedSearch and specific brand/category searches, the lack of usage context is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get AI recipe suggestions using a product
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrBarcode | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully communicate behavioral traits. It only says 'AI recipe suggestions', implying generation, but does not disclose required permissions, response time, error behavior, or whether it requires internet access. Critical details for a generative tool are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is efficient and front-loaded. It wastes no words, though slightly more detail could be included without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and no annotations, the description should compensate by explaining what the output looks like (e.g., a list of recipes). It does not, leaving the agent without key information about expected results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'nameOrBarcode' has 0% schema description coverage, and the description merely says 'using a product', offering no format expectations, examples, or constraints beyond the schema type. The parameter name is self-descriptive, but the description adds minimal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates AI recipe suggestions based on a product. It uses a specific verb ('Get') and resource ('AI recipe suggestions'), and the context of 'using a product' differentiates it from sibling tools that focus on product lookup or analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like searchProducts or analyzeProduct. There is no mention of prerequisites, limitations, or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.0advancedSearchanalyzeProductautocompletecheckMultipleAllergenscompareProductsgetAdditivesInfogetAllergenCheckgetEcoScoregetInsightTypesgetNutriScoregetProductAIQuestionsgetProductByBarcodegetProductInsightsgetProductPricesgetRandomAIQuestionsgetRecentPricessearchByBrandsearchByCategorysearchPricessearchProductssuggestRecipesScored across 21 tools
Each tool has a clearly distinct purpose: search tools differ by scope (general, brand, category, advanced filters), nutritional/environmental checks are separate, AI insight tools are well-differentiated (questions vs. insights, per-product vs. random), and price tools cover different query patterns. No two tools are easily confused.
All tool names follow a consistent camelCase verb-noun pattern (e.g., 'searchByBrand', 'getEcoScore', 'analyzeProduct'). The verbs vary logically by action, and there is no mixing of naming conventions like snake_case or underscores.
With 21 tools, the set is slightly larger than typical but still well-scoped. Each tool covers a specific feature of the Open Food Facts database (search, nutrition, environment, allergens, AI insights, prices, recipes) without significant overlap or redundancy.
For a read-only query server, the tool set is comprehensive: it covers product lookup, multiple search dimensions, nutritional and environmental ratings, allergen checking, AI-driven insights, and pricing data. Missing write operations (create/update/delete) are outside the apparent scope, so only minor gaps exist (e.g., no direct list of all categories or brands, but autocomplete covers that).
Unlock the power of food transparency with our Open Food Facts MCP server. Easily look up any food
Barcode lookup, nutrition search, and product comparison for 3M+ crowd-sourced food products.
Food and nutrition data: search, macros, and comparisons
Open Food Facts — collaborative food product database