Offers git workflow assistance through the gitHelper tool to support Open Food Facts development processes.
Provides tools for analyzing GitHub issues, creating issue roadmaps, and accessing Open Food Facts repositories for development tasks.
Enables connection to the Open Food Facts MCP server through VS Code extension to enhance AI assistance with food product information and development tools.
Supports optimization of MongoDB queries in developer mode with specific prompts for database operations.
Required for running the MCP server and supported as part of the development environment.
Supported as a package manager for installing and managing the MCP server dependencies.
Provides development support for Perl code with debugging assistance and code explanation tools for the Open Food Facts codebase.
Click on "Install 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., "@OpenFoodFacts-mcp what's the Nutri-Score for Nutella?"
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: USDA Nutrition 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, so the description carries the full burden. It does not disclose pagination behavior, read-only nature, rate limits, or return format. Minimal behavioral insight beyond listing filters.
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?
A single sentence that efficiently lists the key filters. No wasted words, though it could be slightly more structured (e.g., separating the purpose from the filter list).
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 12 parameters, no output schema, and no annotations, the description is too brief. It lacks typical usage guidance, return format, or example queries, leaving significant gaps for an agent.
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 75%, and the description merely lists filter categories already documented in the schema. No additional meaning or context is added for parameters.
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 'Advanced product search with multiple filters', specifying the verb 'search' and the resource 'products'. It distinguishes from siblings like 'searchProducts' by emphasizing advanced filtering.
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 multiple filters are needed, but no explicit guidance on when to use this versus other search tools (e.g., searchByBrand, searchProducts) or when not to use it.
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 are provided; the description must cover behavioral traits. It does not disclose whether the tool is read-only, if it requires authentication, or what the AI analysis entails (e.g., potential costs). The description is too sparse.
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, front-loaded with the key purpose. No unnecessary words. However, it could include more detail without being overly long.
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 a single parameter and no output schema or annotations, the description is too brief. It fails to provide adequate context for an agent to invoke the tool correctly, such as what the result will contain or any constraints.
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 only parameter 'nameOrBarcode' has no description in schema (0% coverage) and the description does not explain what values it accepts (product name? barcode format?). The tool name suggests it analyzes a product, but the parameter semantics are unclear.
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 AI nutritional analysis of a product' clearly indicates the action (Get) and the resource (AI nutritional analysis). It distinguishes from siblings like getProductByBarcode which provide raw data, not analysis. However, 'nutritional analysis' could be 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 siblings. For example, when to choose this over getProductByBarcode or compareProducts is not mentioned. No context of when not to use it.
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 present, so the description must disclose behavior. It states the function but does not mention side effects, authentication requirements, or rate limits. For a simple read-only operation, the transparency is adequate but lacks depth.
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 12 words that efficiently conveys the tool's purpose and scope. Every part is necessary, and there is no redundancy.
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 autocomplete tool with 4 parameters and no output schema, the description covers the essential information. It could mention the return format or typical use case, but it is largely 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?
With 100% schema description coverage, the baseline is 3. The description does not add meaningful context beyond what the schema already provides; it merely repeats the taxonomy types. No additional parameter usage guidance is given.
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 provides autocomplete suggestions for specific taxonomy types (categories, brands, labels, ingredients, allergens, additives). The verb 'Get autocomplete suggestions' and the listed resources make the purpose distinct from sibling tools like searchProducts or searchByBrand.
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 for autocomplete input scenarios but does not explicitly state when to use this tool over alternatives like searchProducts or advancedSearch. No guidance on when not to use or prerequisites is provided.
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?
No annotations are present, and the description fails to disclose behavioral traits such as whether the tool is read-only, requires authentication, or has side effects. This leaves the agent with insufficient information about the operation's safety.
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, very short sentence that conveys the core purpose without any extraneous information. It is front-loaded and 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?
Given the tool's simplicity (two parameters, no output schema), the description is minimally adequate but lacks explanation of the return type or behavior. It does not clarify if the result is a boolean or a list, or how the check handles unknown allergens.
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%, so both parameters are already documented. The description does not add new semantics beyond rephrasing the parameter types; it merely reinforces the array nature of allergens without providing additional context or constraints.
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 specifies the verb (check) and resource (product for multiple allergens) and distinguishes from the sibling getAllergenCheck by indicating 'multiple allergens at once'. However, it does not explicitly state the output format (e.g., boolean or list).
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 getAllergenCheck for a single allergen. The absence of such context may lead to inappropriate tool selection.
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?
With no annotations, the description must convey behavior. The phrase 'using AI' is vague and does not disclose specifics such as what data is returned, whether the tool is read-only, or any side effects. The agent cannot anticipate the comparison criteria or output format.
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 extremely short (one phrase), which makes it concise but lacking structure. It is front-loaded but omits necessary details, making it minimally adequate.
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 two-parameter schema and no output schema, the description is incomplete. It fails to explain what the comparison yields, how results are presented, or any behavioral context. The agent would need to infer or test to understand the tool fully.
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 clarify parameters. The parameter names 'nameOrBarcode1' and 'nameOrBarcode2' are somewhat self-explanatory, but the description adds no additional meaning or constraints (e.g., format, examples). The agent benefits only from the names, not the description.
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 ('Compare') and the resource ('two products'), and mentions 'using AI' to indicate automated analysis. It distinguishes from sibling 'analyzeProduct' which is for single products. However, it lacks specifics on what aspects are compared, slightly reducing clarity.
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 'analyzeProduct' or 'searchProducts'. No context on prerequisites or exclusions is given, leaving the agent uncertain about appropriate usage.
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 must fully disclose behavior. It only states it 'lists all additives', but does not address edge cases (e.g., product not found, no additives), error handling, or response format. Critical behavioral details are missing for a mutation-free tool.
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?
A single, front-loaded sentence with no extraneous words. Every word contributes to understanding what the tool does.
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?
Without an output schema, the description should clarify return structure. It mentions E-numbers and NOVA level, but does not specify if the output is a list of objects or strings, or whether additional fields exist. This is adequate for a simple list tool but 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?
Schema coverage is 100%, so the schema already documents the parameter. The description adds no additional semantics beyond the schema's description. Baseline score of 3 is appropriate as the description does not enhance understanding.
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 resource 'additives in a product', and specifies outputs 'E-numbers and NOVA processing level'. This clearly distinguishes it from sibling tools like getProductByBarcode (full product info) and getNutriScore (nutrition).
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 (e.g., searchProducts, getProductByBarcode). The description only states what it does, leaving the agent to infer usage context without supporting conditions or exclusions.
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 provided; description implies read-only but doesn't confirm no side effects or data mutation.
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, front-loads the core action.
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; description omits what 'check' returns (boolean, string?), lacking completeness for a simple 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?
Input schema provides 100% coverage for both parameters; description adds example allergens but little additional meaning.
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 checks for a specific allergen with examples, but does not differentiate from sibling 'checkMultipleAllergens'.
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 'checkMultipleAllergens' or any prerequisites.
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?
With no annotations, the description should disclose behavioral traits. It only mentions the output but does not specify error handling, prerequisites (e.g., product existence), or rate limits.
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 wasted words. It is appropriately front-loaded.
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 mentions the rating range A-E but does not specify the return format (e.g., string, object). It lacks details on what happens if the product is not found. For a simple tool, it is partially 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?
The input schema covers the parameter with a description; the description adds no new meaning beyond what is already in the schema. 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 (A-E rating) for a product, with a specific verb and resource. It is distinct from sibling tools 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 is provided on when to use this tool versus alternatives (e.g., getNutriScore or searchProducts). There is no explicit context for usage or exclusions.
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 fully disclose behavioral traits. It only states 'Get a summary' without mentioning safety (read-only), authorization, rate limits, or what the summary contains.
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 no wasted words. Information is front-loaded and easy to parse.
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 simplicity, the description could specify what the summary includes (e.g., list of types, counts) to be more complete, but it is minimally adequate for a parameterless 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?
Tool has zero parameters, and the description adds no further parameter info, which is acceptable per guidelines (baseline 4). No parameter details are needed beyond the empty 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?
Description clearly states it retrieves a summary of available AI insight types in Robotoff, using a specific verb and resource. This distinguishes it from sibling tools like getProductInsights which retrieve insights for specific products.
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 for obtaining a list of insight types, but provides no explicit when-to-use or when-not-to-use guidance, nor references to alternative tools.
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?
No annotations provided. Description fails to disclose any behavioral traits (e.g., read-only, rate limits, or data freshness). The agent is left without critical safety or performance info.
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, front-loaded, zero redundancy. Efficient communication of the tool's essence.
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 (1 param, no output schema) but many siblings, the description is adequate but lacks return format info or what Nutri-Score is, leaving some ambiguity.
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 already describes the parameter well (100% coverage). Description adds only a high-level phrase ('quick health assessment') that doesn't enhance parameter understanding. Baseline met.
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 it retrieves Nutri-Score grade (A-E) for a product. Verb and resource are specific, and it distinguishes from siblings like getEcoScore.
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 alternative guidance. While the tool's purpose is clear, it doesn't differentiate from similar tools like getEcoScore, leaving the agent to infer usage 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 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 are provided, so the description carries the burden. It states the tool returns AI-generated questions but does not discuss edge cases (e.g., missing barcode), read-only nature, or any side effects. The description is basic but not 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 (20 words) with an illustrative parenthetical example. No redundant information, efficiently conveys the tool's purpose.
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 adequately explains what the tool returns (questions needing verification) and gives examples. However, it does not specify the output structure (e.g., list of strings), which would add completeness.
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 'barcode' parameter already described as 'Product barcode (EAN/UPC)'. The tool description adds no additional semantics, format details, or examples 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 retrieves AI-generated questions about a product needing human verification, with specific examples. It distinguishes from sibling 'getRandomAIQuestions' by focusing on a specific product via barcode.
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 for obtaining verification questions but provides no explicit guidance on when to use this tool over alternatives like 'getRandomAIQuestions', nor any prerequisites or exclusions.
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; description fails to mention response structure, error handling, or restrictions like rate limits. Minimal behavioral 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, no redundancy. Could be slightly expanded for clarity but remains appropriately concise.
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 simplicity, lacks definition of 'product details' and handling of invalid barcodes. Incomplete for agent decision-making.
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?
Parameter 'barcode' has no description in schema (0% coverage). Description only repeats 'barcode (EAN/UPC)', adding no format or validation details.
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 verb (Get product details) and resource (barcode). Specifies barcode type (EAN/UPC), differentiating from sibling tools like searchByBrand.
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?
Indicates usage for exact barcode lookup but lacks explicit 'when not to use' or mention of alternative tools for partial searches.
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?
No annotations exist, so description must disclose behavioral traits. It mentions 'AI-generated' but does not explain performance implications, required permissions, or how parameters affect results.
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 is concise and front-loaded with the core action. No wasted words, but could be slightly more structured with bullet examples.
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?
Does not describe return format, pagination behavior, or how multiple parameters combine. With no output schema, this is a significant gap.
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 description adds no extra meaning beyond what the schema already provides. 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?
Clearly states the tool retrieves AI-generated insights about products and lists examples like labels and categories, which distinguishes it from sibling tools like getProductByBarcode or analyzeProduct.
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 other insight-related tools (e.g., getInsightTypes, analyzeProduct) or when to avoid it. No context provided.
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?
No annotations are provided, so the description must disclose behavioral traits. It only implies 'get' is read-only but does not confirm safety, authentication needs, rate limits, or response behavior. The description lacks sufficient transparency for a tool with no annotations.
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, efficient sentence that front-loads the purpose. However, it could include more detail without becoming overly long, balancing conciseness with completeness.
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 3 parameters, no output schema, and no annotations, the description is incomplete. It does not describe the output structure, pagination behavior, or data sources, leaving critical gaps for an agent working with multiple similar 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?
With only 33% schema description coverage (only 'barcode' is described), the description should compensate by explaining parameters. It does not mention 'page' or 'pageSize', nor does it clarify the barcode format. The brief description adds minimal semantic value 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 it retrieves crowd-sourced price data for a specific product, with the intent to find lower prices. It distinguishes itself from sibling tools like getRecentPrices or searchPrices by explicitly referencing crowd-sourced data and focusing on a single product.
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. It does not mention prerequisites, exclusions, or compare with sibling tools like searchPrices or getRecentPrices, leaving the agent without contextual direction.
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 provided, so description carries full burden. It mentions 'AI-generated' and 'need human verification' indicating the data source and purpose, but lacks details on read-only nature, authentication, rate limits, or mutation potential.
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, concise sentence with no fluff. It front-loads the purpose and use case. Could be marginally improved with structure, but 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?
Sufficient for a simple random fetch tool with 4 optional parameters and no output schema. However, lacks hints about return format or pagination, which would enhance completeness.
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 description adds no parameter-specific information beyond the schema. 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 it retrieves random AI-generated questions from Robotoff for human verification, with a community contribution use case. It distinguishes itself from sibling 'getProductAIQuestions' by emphasizing 'random' and 'need human verification', though not explicitly named.
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 community contribution but does not explicitly state when to use vs alternatives like getProductAIQuestions, or any prerequisites. No when-not or alternative guidance.
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 exist, and the description does not disclose behavioral traits such as pagination behavior, data freshness, ordering details, or what fields are returned. The phrase 'recently added' is vague and lacks precision.
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, but it is too vague to be considered efficient. It lacks crucial information, making it under-specified rather than concise.
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 no annotations, no output schema, and 0% schema description coverage, the description is insufficient. It does not explain what 'price data' includes, how results are ordered, or how it relates to sibling 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?
The input schema has two parameters (page, pageSize) with no descriptions, and the tool description provides zero explanation of them. With 0% schema description coverage, the description should compensate but fails entirely.
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 the 'most recently added price data from the community', specifying the verb 'get' and the resource. However, it does not explicitly differentiate from siblings like 'getProductPrices' 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 such as 'searchPrices' (which might allow filters) or 'getProductPrices' (likely for a specific product). Agents are left to infer usage without explicit context.
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 provided, so description must carry full burden. Only states 'find all products' but omits pagination behavior, read-only nature, or any side effects. 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 with 8 words, no redundancy. Efficient but slightly under-informative for the tool's purpose.
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. Lacks details on result format, pagination limits, matching behavior (exact vs partial), or sorting. Incomplete for a search tool with 3 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 coverage is only 33% (only 'brand' has description). Description does not add meaning beyond 'brand name' or clarify 'page'/'pageSize' usage. Fails to compensate for uncovered parameters.
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 verb+resource: 'Find all products from a specific brand'. It is specific but does not differentiate from sibling tools like searchProducts or searchByCategory, which also find products.
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 when-not-to-use or context about prerequisites or preferred scenarios.
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?
No annotations are provided, so description must carry full behavioral burden. It only states the action and category scope but omits pagination behavior, result format, or potential errors. Key traits like default page size are not mentioned.
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 is efficient and front-loaded. Every word adds value, 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?
For a simple search tool with no output schema, the description captures core purpose but misses pagination details and ordering. Adequate but could provide more context for agent decision-making.
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 33% with only category described (via description). Page and pageSize lack descriptions in schema, and the tool description does not explain their purpose or defaults, leaving ambiguity for the agent.
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 'Search products within a specific food category' with examples like beverages, snacks, dairy, cereals. This distinguishes it from siblings like searchByBrand and searchProducts, which target different attributes.
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?
Description implies use when you need to filter by category, but does not explicitly state when not to use it or compare with sibling tools like advancedSearch. No guidance on when to prefer this tool.
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?
No annotations are present, so the description must bear the full burden. It does not disclose whether the tool is read-only, destructive, or has any side effects. For a search tool, read-only behavior is implied but not stated, which 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 that covers the core functionality. Every word is useful, no fluff.
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 minimal for a tool with 6 parameters and no output schema. It lacks details about pagination results, ordering, and expected output format. Usage context is absent.
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 input schema already provides clear descriptions for all six parameters (100% coverage). The description merely lists 'barcode, currency, etc.' which adds no new semantics beyond the schema. 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 it searches for crowd-sourced price data with filters like barcode and currency. It uses a specific verb-resource combination. However, it does not explicitly differentiate from siblings like getProductPrices, which might also retrieve price information.
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., getProductPrices, searchProducts). The description does not mention exclusions or prerequisites.
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 carries full burden for behavioral disclosure. It only states 'Search products' without mentioning pagination behavior (despite page and pageSize in schema), result format, or any side effects. The description fails to convey important 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?
The description is a single short sentence, making it concise. However, the conciseness comes at the cost of omitting necessary details, so it is not an optimal balance.
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 presence of many sibling search tools and three parameters (one required), the description is too minimal. It does not explain how the query parameter works, what results are returned, or how pagination functions. The lack of an output schema increases the need for a comprehensive description.
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?
Input schema has 0% description coverage for parameters, and the description does not explain the 'query' parameter or how it maps to the mentioned fields (name, brand, category). The default values for page and pageSize are not elaborated. The description adds no meaning beyond the schema structure.
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 'Search' and the resource 'products', and specifies the searchable fields (name, brand, or category). This distinguishes it from sibling tools like searchByBrand and searchByCategory, which are more specific. However, it could be more explicit about combining multiple fields.
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 such as advancedSearch, searchByBrand, or searchByCategory. There is no mention of use cases, prerequisites, or exclusions, leaving the agent without context for selection.
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?
No annotations are provided, so the description alone must disclose behavioral traits. It only mentions 'AI' but fails to convey limitations, output format, or whether the parameter expects a name or barcode.
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 efficient sentence, front-loaded with the action verb. However, it sacrifices completeness for brevity.
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 tool with no output schema and no annotations, the description omits return values, error conditions, and parameter details, making it insufficient for reliable invocation.
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 must compensate. It only vaguely says 'using a product' without clarifying the parameter format or constraints beyond its name.
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 'Get AI recipe suggestions using a product,' specifying a verb and resource, and distinguishes this tool from siblings like searchByBrand or getProductByBarcode which are product-centric.
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 recipe suggestions are needed for a product, but lacks explicit when-not-to-use or alternative recommendations. Siblings are all product data tools, making this unique.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but some overlap exists between search tools (advancedSearch, searchByBrand, searchByCategory) and allergen check tools (getAllergenCheck, checkMultipleAllergens). However, descriptions clarify differences, making selection manageable.
Tool names follow a consistent verb+noun pattern (e.g., getProductByBarcode, searchByBrand, checkMultipleAllergens). Even longer names like getProductAIQuestions maintain clarity. No mixing of conventions or obscure verbs.
With 21 tools, the set is comprehensive for a food database API. While slightly above typical ideal range, each tool serves a specific function (search, details, scores, allergies, prices, AI insights). No unnecessary redundancy.
The tool set covers key read operations for OpenFoodFacts: search, product details, nutritional scores, allergens, prices, and AI insights. Missing create/update/delete, but that aligns with a read-only public API. Minor gaps like direct nutrient data access are mitigated by analyzeProduct.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Unlock the power of food transparency with our Open Food Facts MCP server. Easily look up any food
Nutrition MCP — wraps Open Food Facts API (free, no auth)
Recipes MCP — wraps TheMealDB API (free tier, no auth)
MCP server for real-time product search by barcode (EAN, UPC, GTIN) or keyword on ean-search.org
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/JagjeevanAK/OpenFoodFacts-MCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
