Skip to main content
Glama

Search USDA Foods

usda_search_foods
Read-only

Search USDA FoodData Central foods by keyword. Returns matching foods with FDC IDs and available preview nutrients: protein (1003), fat (1004), carbohydrate (1005), fiber (1079, and 2033 for AOAC 2011.25 total dietary fiber, a separate measure some Foundation foods report beside or instead of 1079), and energy (1008, 1062, 2047, 2048), preserving distinct fiber and energy measures. Missing nutrients are omitted. Use the returned fdcId with usda_get_food for other nutrients or the full profile, or usda_compare_foods for side-by-side comparisons. When dataType is omitted, defaults to SR Legacy (common whole foods with complete profiles), to Branded when brandOwner is set (only Branded records carry one), or to Branded and Survey (FNDDS) when the query is 8–14 digits alone (a UPC/GTIN barcode or an FNDDS food code). A 12–14-digit barcode with a valid check digit also matches the other digit forms FDC stores it in. Set dataType to ["Branded"] for packaged products. Pass brandOwner (e.g. "General Mills") to narrow branded results.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "usda_search_foods"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesSearch terms — food name, ingredient, or UPC/GTIN code. Examples: "chicken breast raw", "banana", "02114029705". A food matching any one unqualified word counts, so a multi-word query also returns foods holding only some of its words; set requireAllWords, or prefix each word with +, to require them all. A query of 8–14 digits alone matches a Branded UPC/GTIN code or an 8-digit Survey (FNDDS) food code. A 12-, 13-, or 14-digit code with a valid GTIN check digit (a printed UPC-A or EAN-13) also matches the other digit forms FDC stores that GTIN in: leading zeros added or dropped down to 12 digits, and the 12-digit form without its check digit. Any other code matches only as FDC stores it, leading zeros included. FDC reads Lucene syntax: "quoted phrases", +required and -excluded terms, AND/OR/NOT, wildcards (chick*), fuzzy matches (beeef~), boosts (beef^5), grouping parentheses, field:value, regex terms (/chick.*/), and ranges ([a TO c], {a TO c}). Any other slash, bracket, or brace (1/8, w/o, beef [raw]), any unpaired parenthesis, and every double quote when the query holds an odd number of them are sent as literal characters.
dataTypeNoFDC data sources to search. Omitting this defaults to ["SR Legacy"] (common whole foods, complete nutrient profiles), to ["Branded"] when brandOwner is set, or to ["Branded", "Survey (FNDDS)"] when the query is 8–14 digits alone (a UPC/GTIN barcode or an FNDDS food code). Include "Branded" for packaged products. Multiple values allowed.
pageSizeNoNumber of results per page. Default 10; a larger value returns at most 200 and says so (a server configured with strict limits rejects more than 200).
brandOwnerNoFilter branded results by brand owner name (e.g. "General Mills", "Kraft"). Matched as one phrase, ignoring case and punctuation: "Kellogg Company" matches owners holding those words in that order. A value containing * or ? is sent as wildcard terms instead, each word matched on its own (e.g. "Kellog*"). For other operators, use field syntax in query (e.g. "+cereal +brandOwner:Kellog*"). Only Branded records carry one, so setting this defaults dataType to ["Branded"] unless dataType is given explicitly.
pageNumberNoPage number (1-based), counted at the pageSize served. Use with totalPages to paginate. FDC serves only the first 100,000 results of a search, so a page whose pageSize × pageNumber exceeds 100,000 fails with result_window_exceeded, naming the last reachable page, unless it is also past the last page. A page past the last returns empty foods with a notice naming the last reachable page when the query has matches.
foodCategoryNoFilter by USDA food category (e.g. "Poultry Products", "Vegetables and Vegetable Products"). Matched as one phrase, ignoring case and punctuation. A value containing * or ? is sent as wildcard terms instead, each word matched on its own (e.g. "Poult*"); a whole word followed by * can match nothing ("Poultry*" does), so shorten it. For other operators, use field syntax in query (e.g. chicken -foodCategory:"Fast Foods" excludes a category).
requireAllWordsNoMatch only foods containing every query word (FDC requireAllWords). Default false: a food matching any one word counts. Explicit OR and "quoted phrases" keep their meaning.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
foodsNoFoods matching the search query.
noticeNoGuidance when the requested pageSize is above FDC's maximum of 200 and pages are served at 200, when the requested page is past the last reachable page, or when more foods match than the first 100,000 FDC serves.
totalHitsNoTotal number of foods matching the query across all pages.
totalCountNoTotal foods matching the query across all pages.
totalPagesNoTotal number of pages at the pageSize served (the one requested, or 200 when more was requested), as FDC counts them. FDC serves only the first 100,000 results of a search, so when totalHits exceeds 100,000, pages past 100,000 / pageSize (rounded down) are out of reach.
currentPageNoCurrent page number (1-based); the requested page for exhausted pages.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changed
    • changedInput schema / properties / pageNumber / description
      Previous value: -"Page number (1-based). Use with totalPages to paginate. FDC serves only the first 100,000 results of a search, so a page whose pageSize × pageNumber exceeds 100,000 fails with result_window_exceeded, naming the last reachable page, unless it is also past the last page. A page past the last returns empty foods with a notice naming the last reachable page when the query has matches."New value: +"Page number (1-based), counted at the pageSize served. Use with totalPages to paginate. FDC serves only the first 100,000 results of a search, so a page whose pageSize × pageNumber exceeds 100,000 fails with result_window_exceeded, naming the last reachable page, unless it is also past the last page. A page past the last returns empty foods with a notice naming the last reachable page when the query has matches."
    • changedInput schema / properties / pageSize / description
      Previous value: -"Number of results per page. Default 10, maximum 50."New value: +"Number of results per page. Default 10; a larger value returns at most 200 and says so (a server configured with strict limits rejects more than 200)."
    • changedInput schema / properties / pageSize / maximum
      Previous value: -50New value: +9007199254740991
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `query_syntax`: FDC rejected the query syntax, e.g. a dangling operator or a trailing backslash. `no_results`: No foods matched the query in the specified data sources. `result_window_exceeded`: pageSize × pageNumber exceeds the first 100,000 results FDC serves for a search, on a page that holds matches. `retry_deadline_exceeded`: FDC did not answer within the call's 45-second budget, across every attempt. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `query_syntax`: FDC rejected the query syntax, e.g. a dangling operator or a trailing backslash. `no_results`: No foods matched the query in the specified data sources. `result_window_exceeded`: pageSize × pageNumber, at the pageSize served, exceeds the first 100,000 results FDC serves for a search, on a page that holds matches. `retry_deadline_exceeded`: FDC did not answer within the call's 45-second budget, across every attempt. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / foods / items / properties / nutrients / description
      Previous value: -"Available preview nutrients on the food's per-100 basis (basisUnit): protein (1003), fat (1004), carbohydrate (1005), fiber (1079), and energy (1008, 1062, 2047, 2048). Source order, values and distinct energy estimates are preserved. Missing entries are omitted; use usda_get_food for other nutrients."New value: +"Available preview nutrients on the food's per-100 basis (basisUnit): protein (1003), fat (1004), carbohydrate (1005), fiber (1079, and 2033 for AOAC 2011.25 total dietary fiber, a separate measure), and energy (1008, 1062, 2047, 2048). Source order, values and distinct fiber and energy measures are preserved. Missing entries are omitted; use usda_get_food for other nutrients."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when the requested page is past the last reachable page, or when more foods match than the first 100,000 FDC serves."New value: +"Guidance when the requested pageSize is above FDC's maximum of 200 and pages are served at 200, when the requested page is past the last reachable page, or when more foods match than the first 100,000 FDC serves."
    • changedOutput schema / properties / totalPages / description
      Previous value: -"Total number of pages at this pageSize, as FDC counts them. FDC serves only the first 100,000 results of a search, so when totalHits exceeds 100,000, pages past 100,000 / pageSize (rounded down) are out of reach."New value: +"Total number of pages at the pageSize served (the one requested, or 200 when more was requested), as FDC counts them. FDC serves only the first 100,000 results of a search, so when totalHits exceeds 100,000, pages past 100,000 / pageSize (rounded down) are out of reach."
  2. Changed4 schema fields changed
    • changedInput schema / properties / query / description
      Previous value: -"Search terms — food name, ingredient, or UPC/GTIN code. Examples: \"chicken breast raw\", \"banana\", \"02114029705\". A food matching any one unqualified word counts, so a multi-word query also returns foods holding only some of its words; set requireAllWords, or prefix each word with +, to require them all. A query of 8–14 digits alone matches a Branded UPC/GTIN code exactly as FDC stores it, leading zeros included, or an 8-digit Survey (FNDDS) food code. FDC reads Lucene syntax: \"quoted phrases\", +required and -excluded terms, AND/OR/NOT, wildcards (chick*), fuzzy matches (beeef~), boosts (beef^5), grouping parentheses, field:value, regex terms (/chick.*/), and ranges ([a TO c], {a TO c}). Any other slash, bracket, or brace (1/8, w/o, beef [raw]), any unpaired parenthesis, and every double quote when the query holds an odd number of them are sent as literal characters."New value: +"Search terms — food name, ingredient, or UPC/GTIN code. Examples: \"chicken breast raw\", \"banana\", \"02114029705\". A food matching any one unqualified word counts, so a multi-word query also returns foods holding only some of its words; set requireAllWords, or prefix each word with +, to require them all. A query of 8–14 digits alone matches a Branded UPC/GTIN code or an 8-digit Survey (FNDDS) food code. A 12-, 13-, or 14-digit code with a valid GTIN check digit (a printed UPC-A or EAN-13) also matches the other digit forms FDC stores that GTIN in: leading zeros added or dropped down to 12 digits, and the 12-digit form without its check digit. Any other code matches only as FDC stores it, leading zeros included. FDC reads Lucene syntax: \"quoted phrases\", +required and -excluded terms, AND/OR/NOT, wildcards (chick*), fuzzy matches (beeef~), boosts (beef^5), grouping parentheses, field:value, regex terms (/chick.*/), and ranges ([a TO c], {a TO c}). Any other slash, bracket, or brace (1/8, w/o, beef [raw]), any unpaired parenthesis, and every double quote when the query holds an odd number of them are sent as literal characters."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `query_syntax`: FDC rejected the query syntax, e.g. a dangling operator or a trailing backslash. `no_results`: No foods matched the query in the specified data sources. `result_window_exceeded`: pageSize × pageNumber exceeds the first 100,000 results FDC serves for a search, on a page that holds matches. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `query_syntax`: FDC rejected the query syntax, e.g. a dangling operator or a trailing backslash. `no_results`: No foods matched the query in the specified data sources. `result_window_exceeded`: pageSize × pageNumber exceeds the first 100,000 results FDC serves for a search, on a page that holds matches. `retry_deadline_exceeded`: FDC did not answer within the call's 45-second budget, across every attempt. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "query_empty",
      -  "query_syntax",
      -  "no_results",
      -  "result_window_exceeded"
      -]New value: +[
      +  "query_empty",
      +  "query_syntax",
      +  "no_results",
      +  "result_window_exceeded",
      +  "retry_deadline_exceeded"
      +]
    • changedOutput schema / properties / foods / items / properties / gtinUpc / description
      Previous value: -"UPC/GTIN barcode as FDC stores it, leading zeros kept (e.g. \"02114029705\"). Branded only; a query of exactly these digits finds the product again."New value: +"UPC/GTIN barcode as FDC stores it, leading zeros kept (e.g. \"02114029705\"). After a 12–14-digit query it can differ from the query in leading zeros or a missing check digit, naming the stored form that matched. Branded only; a query of exactly these digits finds the product again."
  3. Changed16 schema fields changed
    • changedInput schema / properties / brandOwner / description
      Previous value: -"Filter branded results by brand owner name (e.g. \"General Mills\", \"Kraft\"). Only Branded records carry one, so setting this defaults dataType to [\"Branded\"] unless dataType is given explicitly."New value: +"Filter branded results by brand owner name (e.g. \"General Mills\", \"Kraft\"). Matched as one phrase, ignoring case and punctuation: \"Kellogg Company\" matches owners holding those words in that order. A value containing * or ? is sent as wildcard terms instead, each word matched on its own (e.g. \"Kellog*\"). For other operators, use field syntax in query (e.g. \"+cereal +brandOwner:Kellog*\"). Only Branded records carry one, so setting this defaults dataType to [\"Branded\"] unless dataType is given explicitly."
    • changedInput schema / properties / dataType / description
      Previous value: -"FDC data sources to search. Omitting this defaults to [\"SR Legacy\"] (common whole foods, complete nutrient profiles), or to [\"Branded\"] when brandOwner is set. Include \"Branded\" for packaged products. Multiple values allowed."New value: +"FDC data sources to search. Omitting this defaults to [\"SR Legacy\"] (common whole foods, complete nutrient profiles), to [\"Branded\"] when brandOwner is set, or to [\"Branded\", \"Survey (FNDDS)\"] when the query is 8–14 digits alone (a UPC/GTIN barcode or an FNDDS food code). Include \"Branded\" for packaged products. Multiple values allowed."
    • changedInput schema / properties / foodCategory / description
      Previous value: -"Filter by USDA food category (e.g. \"Poultry Products\", \"Vegetables and Vegetable Products\"). Case-sensitive."New value: +"Filter by USDA food category (e.g. \"Poultry Products\", \"Vegetables and Vegetable Products\"). Matched as one phrase, ignoring case and punctuation. A value containing * or ? is sent as wildcard terms instead, each word matched on its own (e.g. \"Poult*\"); a whole word followed by * can match nothing (\"Poultry*\" does), so shorten it. For other operators, use field syntax in query (e.g. chicken -foodCategory:\"Fast Foods\" excludes a category)."
    • changedInput schema / properties / pageNumber / description
      Previous value: -"Page number (1-based). Use with totalPages to paginate. Pages past the end return empty foods with a notice when the query has matches."New value: +"Page number (1-based). Use with totalPages to paginate. FDC serves only the first 100,000 results of a search, so a page whose pageSize × pageNumber exceeds 100,000 fails with result_window_exceeded, naming the last reachable page, unless it is also past the last page. A page past the last returns empty foods with a notice naming the last reachable page when the query has matches."
    • changedInput schema / properties / query / description
      Previous value: -"Search terms — food name, ingredient, or UPC/GTIN code for branded products. Examples: \"chicken breast raw\", \"banana\", \"012345678901\". FDC reads Lucene syntax: \"quoted phrases\", +required and -excluded terms, AND/OR/NOT, wildcards (chick*), fuzzy matches (beeef~), boosts (beef^5), grouping parentheses, field:value, regex terms (/chick.*/), and ranges ([a TO c], {a TO c}). Any other slash, bracket, or brace (1/8, w/o, beef [raw]), any unpaired parenthesis, and every double quote when the query holds an odd number of them are sent as literal characters."New value: +"Search terms — food name, ingredient, or UPC/GTIN code. Examples: \"chicken breast raw\", \"banana\", \"02114029705\". A food matching any one unqualified word counts, so a multi-word query also returns foods holding only some of its words; set requireAllWords, or prefix each word with +, to require them all. A query of 8–14 digits alone matches a Branded UPC/GTIN code exactly as FDC stores it, leading zeros included, or an 8-digit Survey (FNDDS) food code. FDC reads Lucene syntax: \"quoted phrases\", +required and -excluded terms, AND/OR/NOT, wildcards (chick*), fuzzy matches (beeef~), boosts (beef^5), grouping parentheses, field:value, regex terms (/chick.*/), and ranges ([a TO c], {a TO c}). Any other slash, bracket, or brace (1/8, w/o, beef [raw]), any unpaired parenthesis, and every double quote when the query holds an odd number of them are sent as literal characters."
    • addedInput schema / properties / requireAllWords
      Added value: +{
      +  "default": false,
      +  "description": "Match only foods containing every query word (FDC requireAllWords). Default false: a food matching any one word counts. Explicit OR and \"quoted phrases\" keep their meaning.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `query_syntax`: FDC rejected the query syntax, e.g. a dangling operator or a trailing backslash. `no_results`: No foods matched the query in the specified data sources. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `query_syntax`: FDC rejected the query syntax, e.g. a dangling operator or a trailing backslash. `no_results`: No foods matched the query in the specified data sources. `result_window_exceeded`: pageSize × pageNumber exceeds the first 100,000 results FDC serves for a search, on a page that holds matches. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "query_empty",
      -  "query_syntax",
      -  "no_results"
      -]New value: +[
      +  "query_empty",
      +  "query_syntax",
      +  "no_results",
      +  "result_window_exceeded"
      +]
    • addedOutput schema / properties / foods / items / properties / basisUnit
      Added value: +{
      +  "description": "What the nutrient amounts are per 100 of: \"g\" for every non-Branded food and for Branded labels in g, GRM, or GM; \"ml\" for Branded labels in ml or MLT. Absent when the Branded label unit (e.g. IU, MG), or its absence, fixes neither: the amounts are then per 100 label units, basis unverified.",
      +  "enum": [
      +    "ml",
      +    "g"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / foods / items / properties / gtinUpc
      Added value: +{
      +  "description": "UPC/GTIN barcode as FDC stores it, leading zeros kept (e.g. \"02114029705\"). Branded only; a query of exactly these digits finds the product again.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / foods / items / properties / nutrients / description
      Previous value: -"Available preview nutrients per 100g: protein (1003), fat (1004), carbohydrate (1005), fiber (1079), and energy (1008, 1062, 2047, 2048). Source order, values and distinct energy estimates are preserved. Missing entries are omitted; use usda_get_food for other nutrients."New value: +"Available preview nutrients on the food's per-100 basis (basisUnit): protein (1003), fat (1004), carbohydrate (1005), fiber (1079), and energy (1008, 1062, 2047, 2048). Source order, values and distinct energy estimates are preserved. Missing entries are omitted; use usda_get_food for other nutrients."
    • changedOutput schema / properties / foods / items / properties / nutrients / items / description
      Previous value: -"A preview nutrient entry with ID, name, and amount per 100g."New value: +"A preview nutrient entry with ID, name, and amount on the food's per-100 basis (basisUnit)."
    • changedOutput schema / properties / foods / items / properties / nutrients / items / properties / amount / description
      Previous value: -"Amount per 100g."New value: +"Amount per 100 g, per 100 ml when basisUnit is \"ml\", or per 100 label units when basisUnit is absent."
    • changedOutput schema / properties / foods / items / properties / servingSizeUnit / description
      Previous value: -"Unit for servingSize as FDC reports it: mass (\"g\", \"GRM\", \"GM\", \"MG\"), volume (\"ml\", \"MLT\"), or another unit (\"IU\"). Branded only."New value: +"Unit for servingSize as FDC reports it (e.g. \"GRM\", \"MLT\", \"IU\"); it sets basisUnit. Branded only."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance for a requested page beyond the available range."New value: +"Guidance when the requested page is past the last reachable page, or when more foods match than the first 100,000 FDC serves."
    • changedOutput schema / properties / totalPages / description
      Previous value: -"Total number of pages available."New value: +"Total number of pages at this pageSize, as FDC counts them. FDC serves only the first 100,000 results of a search, so when totalHits exceeds 100,000, pages past 100,000 / pageSize (rounded down) are out of reach."
  4. Changed5 schema fields changed
    • changedInput schema / properties / pageNumber / description
      Previous value: -"Page number (1-based). Use with totalPages to paginate."New value: +"Page number (1-based). Use with totalPages to paginate. Pages past the end return empty foods with a notice when the query has matches."
    • changedOutput schema / properties / currentPage / description
      Previous value: -"Current page number (1-based)."New value: +"Current page number (1-based); the requested page for exhausted pages."
    • changedOutput schema / properties / foods / items / properties / nutrients / description
      Previous value: -"Preview nutrients per 100g — typically energy, protein, fat, carbs for SR Legacy. Not a complete profile; use usda_get_food for the full set."New value: +"Available preview nutrients per 100g: protein (1003), fat (1004), carbohydrate (1005), fiber (1079), and energy (1008, 1062, 2047, 2048). Source order, values and distinct energy estimates are preserved. Missing entries are omitted; use usda_get_food for other nutrients."
    • changedOutput schema / properties / foods / items / properties / servingSizeUnit / description
      Previous value: -"Unit for servingSize as FDC reports it: mass (\"g\", \"GRM\"), volume (\"ml\", \"MLT\"), or another unit (\"IU\", \"MG\"). Branded only."New value: +"Unit for servingSize as FDC reports it: mass (\"g\", \"GRM\", \"GM\", \"MG\"), volume (\"ml\", \"MLT\"), or another unit (\"IU\"). Branded only."
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Guidance for a requested page beyond the available range.",
      +  "type": "string"
      +}
  5. Changed5 schema fields changed
    • changedInput schema / properties / query / description
      Previous value: -"Search terms — food name, ingredient, or UPC/GTIN code for branded products. Examples: \"chicken breast raw\", \"banana\", \"012345678901\"."New value: +"Search terms — food name, ingredient, or UPC/GTIN code for branded products. Examples: \"chicken breast raw\", \"banana\", \"012345678901\". FDC reads Lucene syntax: \"quoted phrases\", +required and -excluded terms, AND/OR/NOT, wildcards (chick*), fuzzy matches (beeef~), boosts (beef^5), grouping parentheses, field:value, regex terms (/chick.*/), and ranges ([a TO c], {a TO c}). Any other slash, bracket, or brace (1/8, w/o, beef [raw]), any unpaired parenthesis, and every double quote when the query holds an odd number of them are sent as literal characters."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `no_results`: No foods matched the query in the specified data sources. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `query_syntax`: FDC rejected the query syntax, e.g. a dangling operator or a trailing backslash. `no_results`: No foods matched the query in the specified data sources. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "query_empty",
      -  "no_results"
      -]New value: +[
      +  "query_empty",
      +  "query_syntax",
      +  "no_results"
      +]
    • changedOutput schema / properties / foods / items / properties / servingSize / description
      Previous value: -"Serving size in grams from the product label. Branded only."New value: +"Serving size from the product label, in servingSizeUnit. Branded only."
    • changedOutput schema / properties / foods / items / properties / servingSizeUnit / description
      Previous value: -"Unit for servingSize (usually \"g\"). Branded only."New value: +"Unit for servingSize as FDC reports it: mass (\"g\", \"GRM\"), volume (\"ml\", \"MLT\"), or another unit (\"IU\", \"MG\"). Branded only."
  6. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "totalHits",
      +      "currentPage",
      +      "totalPages",
      +      "foods",
      +      "totalCount"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `no_results`: No foods matched the query in the specified data sources. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "query_empty",
      +            "no_results"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "totalHits",
      -  "currentPage",
      -  "totalPages",
      -  "foods",
      -  "totalCount"
      -]
  7. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only say readOnlyHint and openWorldHint; the description adds substantial behavioral context beyond that: missing nutrients are omitted, distinct fiber (1079 vs 2033) and energy measures are preserved rather than collapsed, and the 8–14 digit query form also matches variant digit encodings of a GTIN. It is a read-only remote lookup, and nothing here contradicts the annotations.

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

Conciseness3/5

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

Front-loaded correctly, but the paragraph is dense and includes a nutrient-ID digression ("protein (1003), fat (1004)... energy (1008, 1062, 2047, 2048)") that the output schema already covers and that a caller does not need to choose the tool. The syntax and barcode edge cases are better placed in the query parameter description where they already appear.

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

Completeness5/5

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

For a 7-parameter search tool with an output schema and only safety annotations, the description covers the surprising cases an agent would otherwise hit: default dataType resolution, pagination limits, omitted nutrients, and the distinction between fiber and energy measures. Nothing needed to call it correctly is missing.

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 description coverage is 100% and the description largely restates it — the digit-form matching, Lucene syntax, brandOwner phrase matching, and the 100,000-result window are all already in the parameter descriptions. It does usefully consolidate cross-parameter defaults (brandOwner implies Branded; digit-only query switches to Branded + Survey) in one place, but that too is present in the schema, so this is baseline rather than added meaning.

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

Purpose5/5

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

Opens with a specific verb+resource+scope: "Search USDA FoodData Central foods by keyword." It then names the exact sibling handoffs (usda_get_food for full profiles, usda_compare_foods for side-by-side), so an agent can separate search from retrieval without opening another schema.

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

Usage Guidelines5/5

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

Gives concrete when-to-use routing and explicit defaults/shape rules: default dataType depends on whether brandOwner is set or the query is an 8–14 digit code, and "Set dataType to [\"Branded\"] for packaged products. Pass brandOwner ... to narrow branded results." Alternatives and their trigger conditions are stated rather than implied.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.