Forkmate

search_foods

Read-only

Search USDA FoodData Central, Open Food Facts and Forkmate's curated restaurant menus for a named food. Returns up to 5 candidates, each with macros per 100 g, a source label ('USDA', 'Open Food Facts', 'Forkmate' or 'product label', a packaged product's published label read from a cited page and not yet checked by Forkmate), and, when known, serving_grams/serving_label for one household serving. Curated chain-menu candidates include a provenance object that may carry a portion caveat. A query names a food (at least 2 letters, no wildcards); there is no paging. For a bare generic dish ("a burger", "coffee"), the reply also lists details_that_change_it: the details that change that dish's numbers most, such as where it is from, which item, its size and add-ons. All calorie and macro values, including carbohydrates, are estimates from USDA FoodData Central, Open Food Facts, the user's own entry or an AI assistant's estimate — approximate, not lab-measured or specific to a package or batch, and not suitable for insulin dosing (including carb counting for a meal bolus), blood-glucose prediction or any other medical decision.

Input Schema

Name	Required	Description	Default
`limit`	No	Max candidates to return (default and maximum 5).
`query`	Yes	Food to search, e.g. 'greek yogurt' or 'Chipotle chicken'. At least 2 letters; wildcards are not supported.

Output Schema

Name	Required	Description	Default
`candidates`	Yes
`details_that_change_it`	No	For a bare generic dish: the details that change its numbers most (where it's from, which item, size, add-ons).

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 9, 2026

addedOutput schema / properties / details_that_change_it

Added value: +{
+  "description": "For a bare generic dish: the details that change its numbers most (where it's from, which item, size, add-ons).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed1 schema field changedOct 9, 2026

changedOutput schema / properties / candidates / items / properties / provenance / description

Previous value: -"Chain-menu citation: the chain, its data date, its published page, the assumed build and a caveat."New value: +"Citation: the chain or a product label's brand, its data date, its published page, the assumed build and a caveat."

Changed9 schema fields changedOct 1, 2026

changedInput schema / properties / limit / description

Previous value: -"Max candidates to return (default 5, clamped to 1–10)."New value: +"Max candidates to return (default and maximum 5)."

changedInput schema / properties / query / description

Previous value: -"Food to search, e.g. 'greek yogurt' or 'Chipotle chicken'."New value: +"Food to search, e.g. 'greek yogurt' or 'Chipotle chicken'. At least 2 letters; wildcards are not supported."

addedOutput schema / properties / candidates / items / properties / provenance

Added value: +{
+  "description": "Chain-menu citation: the chain, its data date, its published page, the assumed build and a caveat.",
+  "properties": {
+    "as_of": {
+      "description": "A local date, YYYY-MM-DD.",
+      "type": "string"
+    },
+    "assumed_build": {
+      "type": "string"
+    },
+    "caveat": {
+      "type": "string"
+    },
+    "chain": {
+      "type": "string"
+    },
+    "source_url": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "chain",
+    "as_of"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / candidates / items / properties / serving / description
```
Added value: +"The basis the macros are for, e.g. '100 g'."
```

addedOutput schema / properties / candidates / items / properties / serving_approx

Added value: +{
+  "description": "serving_grams is estimated from a drink's volume.",
+  "type": "boolean"
+}

addedOutput schema / properties / candidates / items / properties / source / description
```
Added value: +"Where the figures came from, as a label."
```

addedOutput schema / properties / candidates / items / properties / source / enum

Added value: +[
+  "USDA",
+  "Open Food Facts",
+  "Forkmate",
+  "your entry",
+  "estimate"
+]

addedOutput schema / properties / candidates / items / properties / unknown_macros

Added value: +{
+  "description": "Macros missing from the source data: shown as 0 but unknown, not a real zero.",
+  "items": {
+    "enum": [
+      "protein_g",
+      "carb_g",
+      "fat_g"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / candidates / items / required

Previous value: -[
-  "name",
-  "macros",
-  "source"
-]New value: +[
+  "name",
+  "serving",
+  "macros",
+  "source"
+]

Changed1 schema field changedSep 30, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "candidates": {
+      "items": {
+        "description": "A food match. Macros are PER 100 g — scale to the portion before logging.",
+        "properties": {
+          "macros": {
+            "description": "Calories and macros. Estimates, not lab-measured; not for insulin dosing.",
+            "properties": {
+              "carb_g": {
+                "type": "number"
+              },
+              "fat_g": {
+                "type": "number"
+              },
+              "kcal": {
+                "type": "number"
+              },
+              "protein_g": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "kcal",
+              "protein_g",
+              "carb_g",
+              "fat_g"
+            ],
+            "type": "object"
+          },
+          "name": {
+            "type": "string"
+          },
+          "serving": {
+            "type": "string"
+          },
+          "serving_grams": {
+            "type": "number"
+          },
+          "serving_label": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "macros",
+          "source"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "candidates"
+  ],
+  "type": "object"
+}

First observedJul 1, 2026

TDQS

A4/5.0

Behavior5/5

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

Beyond the readOnly/openWorld annotations, the description discloses return shape (up to 5 candidates, macros per 100 g, source labels, serving fields, provenance caveats), the unverified 'product label' status, the absence of paging, and a strong medical-use disclaimer. This is rich context an agent cannot get from annotations alone.

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

Conciseness3/5

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

Front-loaded with the sources, but it is one dense run-on paragraph with redundant source enumeration ('USDA FoodData Central, Open Food Facts, the user's own entry or an AI assistant's estimate') and a deeply nested parenthetical about the 'product label' source that is hard to parse.

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

Completeness4/5

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

Despite an output schema already defining the return, the description supplies enough for correct invocation: sources, candidate cap, query rules, and the medical caveat. Only the provenance/portion-caveat behavior remains vague.

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

Parameters3/5

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

Schema coverage is 100%, so both parameters are already documented; the description's query constraints (2-letter minimum, no wildcards, no paging) largely restate the schema. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Search) plus the exact corpora it searches (USDA FoodData Central, Open Food Facts, Forkmate's curated restaurant menus) and the query unit (a named food). This clearly distinguishes it from siblings like lookup_barcode and get_usual_foods.

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

Usage Guidelines3/5

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

The description establishes context (queries name a food, min 2 letters, no wildcards, no paging, generic-dish behavior) but never names an alternative or states when NOT to use it — e.g. telling the agent to reach for lookup_barcode when a barcode is available.

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

All Forkmate tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.