Skip to main content
Glama

cpsc-recalls-mcp-server

Search CPSC Recalls

cpsc_search_recalls
Read-onlyIdempotent

Search consumer product recalls from the CPSC (Consumer Product Safety Commission) — toys, electronics, furniture, appliances, children's products, tools, and clothing. Give at least one text filter or date bound; to browse the latest recalls without one, use cpsc_get_recent. Filters combine with AND, and a text filter matches records whose field contains every one of its words, in any order — each word as a case-insensitive substring with no stemming, so "fire" also matches fireworks and "battery" misses batteries; search a stem instead ("batter" finds battery and batteries). Start with title_search when you have a product in hand — CPSC titles carry the brand, product, and hazard phrasing. For hazard types ("fire", "choking", "burn"), use hazard_search, which matches hazard descriptions, product names, and remedy instructions. When manufacturer finds nothing, try importer, retailer, or distributor: many recalls name one of those as the responsible company. Page past limit with offset — total_found counts every match and has_more says whether more remain; a page returns fewer than limit recalls when it reaches the 64,000-byte response size budget. Pass a recall_number to cpsc_get_recall for the full record, including the complete description, all images, and incident reports. CPSC jurisdiction: consumer products, including child-resistant packaging for drugs and supplements, ATVs and snowmobiles, bicycle tires, and gun safes and locks; food and drugs (FDA), on-road vehicles and their tires (NHTSA), boats (USCG), pesticides (EPA), and firearms (ATF) belong to other agencies.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "cpsc_search_recalls"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of recalls to return on this page. Defaults to 20. A page holds at most 200: a larger limit, up to 10,000, returns 200 with a notice giving the offset to continue from. A page returns fewer when it reaches the 64,000-byte response size budget; has_more then says more remain.
offsetNoSkip this many matching records before returning results. To page through total_found, raise offset by the number of recalls the previous page returned — limit, unless that page reached the response size budget. An offset at or past total_found returns an empty result set rather than an error.
remedyNoKeyword search within the free-text remedy instructions, e.g. "repair", "refund", "firmware update"; matches instructions containing every word, in any order, each as a case-insensitive substring with no stemming. This searches the remedy text, not the remedy_options categories — "repair" matches records whose remedy_options list only "Refund" but whose instructions describe a free repair kit. Combines with the other filters using AND; use hazard_search instead to match remedy text as one of several fields.
date_endNoInclude only recalls on or before this date. ISO 8601 format: "YYYY-MM-DD". Must be a real calendar date, and on or after date_start.
importerNoImporter company name. Matches recalls whose importer names contain every word, in any order, each as a case-insensitive substring with no stemming. Use when searching for recalls by the company that brought the product into the US.
retailerNoRetailer name, e.g. "Walmart", "Target", "Amazon". Matches recalls whose retailer text (store name, dates sold, and price) contains every word, in any order, each as a case-insensitive substring with no stemming.
date_startNoInclude only recalls on or after this date. ISO 8601 format: "YYYY-MM-DD". Must be a real calendar date — "2026-02-31" and "2026-99-99" are rejected.
distributorNoDistributor company name, e.g. "Walmart", "Costco". Matches recalls whose distributor names contain every word, in any order, each as a case-insensitive substring with no stemming — a role distinct from retailer and importer, and listed on far fewer recalls.
updated_endNoInclude only recalls last published by CPSC on or before this date. ISO 8601 format: "YYYY-MM-DD". Must be a real calendar date, and on or after updated_start.
manufacturerNoManufacturer name, e.g. "Samsung", "LEGO". Matches recalls whose manufacturer names contain every word, in any order, each as a case-insensitive substring with no stemming. Many recalls name the importer, retailer, or distributor rather than the manufacturer — try those filters when this finds nothing.
product_nameNoProduct name to search for, e.g. "crib", "space heater", "bicycle". Matches recalls whose product names contain every word, in any order, each as a case-insensitive substring with no stemming — partial words work.
title_searchNoKeyword search within the recall title, e.g. "chandelier", "space heater", "Graco crib". Matches titles containing every word, in any order, each as a case-insensitive substring with no stemming. CPSC titles name the brand, the product, and the hazard, which makes this the highest-signal single filter for most searches.
hazard_searchNoHazard or safety-concept keyword, e.g. "fire", "choking", "burn", "tip-over dresser". Matches when every word appears in the hazard descriptions, product names, or remedy instructions — each word in any of the three, in any order, as a case-insensitive substring with no stemming. The filter to use for hazard types; combine it with another filter to narrow a broad hazard.
updated_startNoInclude only recalls last published by CPSC on or after this date. ISO 8601 format: "YYYY-MM-DD". A separate axis from date_start: a 2003 recall re-published in 2025 matches updated_start "2025-01-01". Use to answer "what has CPSC updated recently". Must be a real calendar date.
description_searchNoKeyword search within the recall description only — not the title, hazard text, or remedy instructions; matches descriptions containing every word, in any order, each as a case-insensitive substring with no stemming. Use for product details not captured in product_name — model numbers, colors, sale channels. For hazard concepts, prefer hazard_search; for the recall headline, prefer title_search.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
noticeNoPresent when the page needs explaining: zero matches (with which criterion to relax), an offset past the last match, a page cut short by the response size budget, or a page held to 200 recalls under a larger limit (each with the offset to continue from).
offsetNoNumber of matching records skipped before this window.
recallsNoMatching recalls, ordered newest-first.
has_moreNoTrue when records remain past this window — call again with offset raised by the number of recalls returned.
truncatedNoTrue when matching records remain past this page — always equal to has_more.
source_noteNoProvenance caveat: recall fields are CPSC record text with HTML markup and character codes converted to plain text, not otherwise edited or verified; check cpsc_url before a consumer-facing decision.
total_foundNoTotal matching records, counted after every filter is applied and before offset, limit, and the response size budget narrow the window.
effectiveQueryNoThe search criteria as applied, joined with AND: each non-blank text filter trimmed, the hazard alias resolved to hazard_search, and blank date bounds dropped.
cpsc_jurisdictionNoWhich products CPSC covers, including those near the lines of other agencies, and which agencies own food and drugs (FDA), on-road vehicles and their tires (NHTSA), boats (USCG), pesticides (EPA), and firearms (ATF), with a reminder to search here before routing such a product away.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed17 schema fields changed
    • changedInput schema / properties / description_search / description
      Previous value: -"Keyword search within the recall description only — not the title, hazard text, or remedy instructions; matches descriptions containing every word, in any order. Use for product details not captured in product_name — model numbers, colors, sale channels. For hazard concepts, prefer hazard_search; for the recall headline, prefer title_search."New value: +"Keyword search within the recall description only — not the title, hazard text, or remedy instructions; matches descriptions containing every word, in any order, each as a case-insensitive substring with no stemming. Use for product details not captured in product_name — model numbers, colors, sale channels. For hazard concepts, prefer hazard_search; for the recall headline, prefer title_search."
    • changedInput schema / properties / distributor / description
      Previous value: -"Distributor company name, e.g. \"Walmart\", \"Costco\". Matches recalls whose distributor names contain every word, in any order — a role distinct from retailer and importer, and listed on far fewer recalls."New value: +"Distributor company name, e.g. \"Walmart\", \"Costco\". Matches recalls whose distributor names contain every word, in any order, each as a case-insensitive substring with no stemming — a role distinct from retailer and importer, and listed on far fewer recalls."
    • changedInput schema / properties / hazard_search / description
      Previous value: -"Hazard or safety-concept keyword, e.g. \"fire\", \"choking\", \"burn\", \"tip-over dresser\". Matches when every word appears in the hazard descriptions, product names, or remedy instructions — each word in any of the three, in any order, case-insensitive. The filter to use for hazard types; combine it with another filter to narrow a broad hazard."New value: +"Hazard or safety-concept keyword, e.g. \"fire\", \"choking\", \"burn\", \"tip-over dresser\". Matches when every word appears in the hazard descriptions, product names, or remedy instructions — each word in any of the three, in any order, as a case-insensitive substring with no stemming. The filter to use for hazard types; combine it with another filter to narrow a broad hazard."
    • changedInput schema / properties / importer / description
      Previous value: -"Importer company name. Matches recalls whose importer names contain every word, in any order. Use when searching for recalls by the company that brought the product into the US."New value: +"Importer company name. Matches recalls whose importer names contain every word, in any order, each as a case-insensitive substring with no stemming. Use when searching for recalls by the company that brought the product into the US."
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of recalls to return on this page. Defaults to 20. A page returns fewer when it reaches the 64,000-byte response size budget; has_more then says more remain."New value: +"Maximum number of recalls to return on this page. Defaults to 20. A page holds at most 200: a larger limit, up to 10,000, returns 200 with a notice giving the offset to continue from. A page returns fewer when it reaches the 64,000-byte response size budget; has_more then says more remain."
    • changedInput schema / properties / limit / maximum
      Previous value: -200New value: +10000
    • changedInput schema / properties / manufacturer / description
      Previous value: -"Manufacturer name, e.g. \"Samsung\", \"LEGO\". Matches recalls whose manufacturer names contain every word, in any order. Many recalls name the importer, retailer, or distributor rather than the manufacturer — try those filters when this finds nothing."New value: +"Manufacturer name, e.g. \"Samsung\", \"LEGO\". Matches recalls whose manufacturer names contain every word, in any order, each as a case-insensitive substring with no stemming. Many recalls name the importer, retailer, or distributor rather than the manufacturer — try those filters when this finds nothing."
    • changedInput schema / properties / product_name / description
      Previous value: -"Product name to search for, e.g. \"crib\", \"space heater\", \"bicycle\". Matches recalls whose product names contain every word, in any order — partial words work."New value: +"Product name to search for, e.g. \"crib\", \"space heater\", \"bicycle\". Matches recalls whose product names contain every word, in any order, each as a case-insensitive substring with no stemming — partial words work."
    • changedInput schema / properties / remedy / description
      Previous value: -"Keyword search within the free-text remedy instructions, e.g. \"repair\", \"refund\", \"firmware update\"; matches instructions containing every word, in any order. This searches the remedy text, not the remedy_options categories — \"repair\" matches records whose remedy_options list only \"Refund\" but whose instructions describe a free repair kit. Combines with the other filters using AND; use hazard_search instead to match remedy text as one of several fields."New value: +"Keyword search within the free-text remedy instructions, e.g. \"repair\", \"refund\", \"firmware update\"; matches instructions containing every word, in any order, each as a case-insensitive substring with no stemming. This searches the remedy text, not the remedy_options categories — \"repair\" matches records whose remedy_options list only \"Refund\" but whose instructions describe a free repair kit. Combines with the other filters using AND; use hazard_search instead to match remedy text as one of several fields."
    • changedInput schema / properties / retailer / description
      Previous value: -"Retailer name, e.g. \"Walmart\", \"Target\", \"Amazon\". Matches recalls whose retailer text (store name, dates sold, and price) contains every word, in any order."New value: +"Retailer name, e.g. \"Walmart\", \"Target\", \"Amazon\". Matches recalls whose retailer text (store name, dates sold, and price) contains every word, in any order, each as a case-insensitive substring with no stemming."
    • changedInput schema / properties / title_search / description
      Previous value: -"Keyword search within the recall title, e.g. \"chandelier\", \"space heater\", \"Graco crib\". Matches titles containing every word, in any order. CPSC titles name the brand, the product, and the hazard, which makes this the highest-signal single filter for most searches."New value: +"Keyword search within the recall title, e.g. \"chandelier\", \"space heater\", \"Graco crib\". Matches titles containing every word, in any order, each as a case-insensitive substring with no stemming. CPSC titles name the brand, the product, and the hazard, which makes this the highest-signal single filter for most searches."
    • changedOutput schema / properties / cpsc_jurisdiction / description
      Previous value: -"Which products CPSC covers and which agencies cover the rest — food/drugs (FDA), motor vehicles/tires (NHTSA), boats (USCG), pesticides (EPA), firearms (ATF)."New value: +"Which products CPSC covers, including those near the lines of other agencies, and which agencies own food and drugs (FDA), on-road vehicles and their tires (NHTSA), boats (USCG), pesticides (EPA), and firearms (ATF), with a reminder to search here before routing such a product away."
    • changedOutput schema / properties / notice / description
      Previous value: -"Present when the page needs explaining: zero matches (with which criterion to relax), an offset past the last match, or a page cut short by the response size budget (with the offset to continue from)."New value: +"Present when the page needs explaining: zero matches (with which criterion to relax), an offset past the last match, a page cut short by the response size budget, or a page held to 200 recalls under a larger limit (each with the offset to continue from)."
    • addedOutput schema / properties / recalls / items / properties / distributors
      Added value: +{
      +  "description": "Distributor company names.",
      +  "items": {
      +    "description": "Distributor name.",
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / recalls / items / properties / last_updated
      Added value: +{
      +  "description": "Date last published, ISO 8601.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / recalls / items / properties / recall_number / description
      Previous value: -"Recall identifier (5-digit numeric for 2002+ records, e.g. \"25043\"; 6-char with letter suffix for 1998–2001 records, e.g. \"99003a\"). Pass to cpsc_get_recall for full detail."New value: +"Recall identifier: 5 digits, e.g. \"25043\", with a letter a–d on some 1998–2001 records, e.g. \"99003a\". Pass to cpsc_get_recall for full detail."
    • changedOutput schema / properties / recalls / items / required
      Previous value: -[
      -  "recall_number",
      -  "recall_date",
      -  "title",
      -  "hazards",
      -  "remedy_options",
      -  "remedy_summary",
      -  "products",
      -  "upcs",
      -  "manufacturers",
      -  "importers",
      -  "retailers",
      -  "cpsc_url",
      -  "images",
      -  "data_quality_notes"
      -]New value: +[
      +  "recall_number",
      +  "recall_date",
      +  "last_updated",
      +  "title",
      +  "hazards",
      +  "remedy_options",
      +  "remedy_summary",
      +  "products",
      +  "upcs",
      +  "manufacturers",
      +  "importers",
      +  "retailers",
      +  "distributors",
      +  "cpsc_url",
      +  "images",
      +  "data_quality_notes"
      +]
  2. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_criteria`: No search criterion was given: every text filter was omitted or blank and no date bound was set. `invalid_date_range`: date_start is later than date_end, or updated_start is later than updated_end, so the range can never match. `upstream_error`: The CPSC recall service (saferproducts.gov) was unavailable, timed out, or sent an unreadable response. `upstream_rejected`: CPSC rejected the request instead of returning recalls, and it rejects the same request every time. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_criteria`: No search criterion was given: every text filter was omitted or blank and no date bound was set. `invalid_date_range`: date_start is later than date_end, or updated_start is later than updated_end, so the range can never match. `upstream_error`: The CPSC recall service (saferproducts.gov) was unavailable, timed out, reported a temporary failure reading its recall data, or sent an unreadable response. `upstream_rejected`: CPSC rejected the request instead of returning recalls, and it rejects the same request every time. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / source_note / description
      Previous value: -"Provenance caveat: recall fields are relayed from CPSC unedited and unverified; check cpsc_url before a consumer-facing decision."New value: +"Provenance caveat: recall fields are CPSC record text with HTML markup and character codes converted to plain text, not otherwise edited or verified; check cpsc_url before a consumer-facing decision."
  3. Changed31 schema fields changed
    • changedInput schema / properties / description_search / description
      Previous value: -"Keyword search within the recall Description field only (does not search Title, Hazards, or remedy text). Use for product details not captured in product_name — model numbers, colors, sale channels. For hazard concepts, prefer hazard_search; for the recall headline, prefer title_search."New value: +"Keyword search within the recall description only — not the title, hazard text, or remedy instructions; matches descriptions containing every word, in any order. Use for product details not captured in product_name — model numbers, colors, sale channels. For hazard concepts, prefer hazard_search; for the recall headline, prefer title_search."
    • addedInput schema / properties / description_search / maxLength
      Added value: +500
    • changedInput schema / properties / distributor / description
      Previous value: -"Distributor company name, e.g. \"Walmart\", \"Costco\". Substring match against the Distributors array — a role distinct from retailer and importer, and populated on far fewer records."New value: +"Distributor company name, e.g. \"Walmart\", \"Costco\". Matches recalls whose distributor names contain every word, in any order — a role distinct from retailer and importer, and listed on far fewer recalls."
    • addedInput schema / properties / distributor / maxLength
      Added value: +500
    • changedInput schema / properties / hazard_search / description
      Previous value: -"Hazard or safety-concept keyword, e.g. \"fire\", \"choking\", \"burn\", \"laceration\". Applied client-side after the upstream fetch. Matches when the term appears in any of: hazard descriptions, product names, or remedy instructions (OR across the three, case-insensitive substring). Use this rather than the upstream Hazard parameter, which CPSC recognizes but never matches."New value: +"Hazard or safety-concept keyword, e.g. \"fire\", \"choking\", \"burn\", \"tip-over dresser\". Matches when every word appears in the hazard descriptions, product names, or remedy instructions — each word in any of the three, in any order, case-insensitive. The filter to use for hazard types; combine it with another filter to narrow a broad hazard."
    • addedInput schema / properties / hazard_search / maxLength
      Added value: +500
    • changedInput schema / properties / importer / description
      Previous value: -"Importer company name. Use when searching for recalls by the company that brought the product into the US."New value: +"Importer company name. Matches recalls whose importer names contain every word, in any order. Use when searching for recalls by the company that brought the product into the US."
    • addedInput schema / properties / importer / maxLength
      Added value: +500
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of results to return (applied client-side — the API returns all matches). Defaults to 20."New value: +"Maximum number of recalls to return on this page. Defaults to 20. A page returns fewer when it reaches the 64,000-byte response size budget; has_more then says more remain."
    • changedInput schema / properties / manufacturer / description
      Previous value: -"Manufacturer name, e.g. \"Samsung\", \"LEGO\". Substring match against the Manufacturers array. Note: many recalls list the importer or retailer as the primary org rather than the manufacturer — try importer or retailer if this returns no results."New value: +"Manufacturer name, e.g. \"Samsung\", \"LEGO\". Matches recalls whose manufacturer names contain every word, in any order. Many recalls name the importer, retailer, or distributor rather than the manufacturer — try those filters when this finds nothing."
    • addedInput schema / properties / manufacturer / maxLength
      Added value: +500
    • changedInput schema / properties / offset / description
      Previous value: -"Skip this many matching records before returning results. Combine with limit to page through total_found — e.g. limit 20 with offset 0, 20, 40. An offset at or past total_found returns an empty result set rather than an error."New value: +"Skip this many matching records before returning results. To page through total_found, raise offset by the number of recalls the previous page returned — limit, unless that page reached the response size budget. An offset at or past total_found returns an empty result set rather than an error."
    • changedInput schema / properties / product_name / description
      Previous value: -"Product name to search for, e.g. \"crib\", \"space heater\", \"bicycle\". Substring match — partial names work."New value: +"Product name to search for, e.g. \"crib\", \"space heater\", \"bicycle\". Matches recalls whose product names contain every word, in any order — partial words work."
    • addedInput schema / properties / product_name / maxLength
      Added value: +500
    • changedInput schema / properties / remedy / description
      Previous value: -"Keyword search within the free-text remedy instructions, e.g. \"repair\", \"refund\", \"firmware update\". Substring match, applied upstream. This searches the remedy narrative, not the structured remedy_options enum — \"repair\" matches records whose remedy_options list only \"Refund\" but whose instructions describe a free repair kit. Combines with the other filters using AND; use hazard_search instead to match remedy text as one of several fields."New value: +"Keyword search within the free-text remedy instructions, e.g. \"repair\", \"refund\", \"firmware update\"; matches instructions containing every word, in any order. This searches the remedy text, not the remedy_options categories — \"repair\" matches records whose remedy_options list only \"Refund\" but whose instructions describe a free repair kit. Combines with the other filters using AND; use hazard_search instead to match remedy text as one of several fields."
    • addedInput schema / properties / remedy / maxLength
      Added value: +500
    • changedInput schema / properties / retailer / description
      Previous value: -"Retailer name, e.g. \"Walmart\", \"Target\", \"Amazon\". Substring match against the retailer narrative (which includes store name, dates sold, and price)."New value: +"Retailer name, e.g. \"Walmart\", \"Target\", \"Amazon\". Matches recalls whose retailer text (store name, dates sold, and price) contains every word, in any order."
    • addedInput schema / properties / retailer / maxLength
      Added value: +500
    • changedInput schema / properties / title_search / description
      Previous value: -"Keyword search within the recall Title, e.g. \"chandelier\", \"space heater\", \"inclined sleeper\". Substring match. CPSC titles name the brand, the product, and the hazard, which makes this the highest-signal single filter for most searches."New value: +"Keyword search within the recall title, e.g. \"chandelier\", \"space heater\", \"Graco crib\". Matches titles containing every word, in any order. CPSC titles name the brand, the product, and the hazard, which makes this the highest-signal single filter for most searches."
    • addedInput schema / properties / title_search / maxLength
      Added value: +500
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "recalls",
      -      "total_found",
      -      "truncated",
      -      "offset",
      -      "has_more",
      -      "cpsc_jurisdiction",
      -      "source_note"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "recalls",
      +      "total_found",
      +      "truncated",
      +      "offset",
      +      "has_more",
      +      "cpsc_jurisdiction",
      +      "source_note",
      +      "effectiveQuery"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • changedOutput schema / properties / cpsc_jurisdiction / description
      Previous value: -"CPSC covers consumer products — toys, electronics, furniture, appliances, tools, clothing. Does NOT cover: food/drugs (FDA), motor vehicles/tires (NHTSA), boats (USCG), pesticides (EPA), firearms (ATF)."New value: +"Which products CPSC covers and which agencies cover the rest — food/drugs (FDA), motor vehicles/tires (NHTSA), boats (USCG), pesticides (EPA), firearms (ATF)."
    • addedOutput schema / properties / effectiveQuery
      Added value: +{
      +  "description": "The search criteria as applied, joined with AND: each non-blank text filter trimmed, the hazard alias resolved to hazard_search, and blank date bounds dropped.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: date_start is later than date_end, or updated_start is later than updated_end, so the range can never match. `no_results`: No recalls matched the search filters, including hazard_search. `upstream_error`: The saferproducts.gov API returned a transient error or timed out. `upstream_rejected`: The saferproducts.gov API answered with an error row instead of recall records, which the same request will always produce. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_criteria`: No search criterion was given: every text filter was omitted or blank and no date bound was set. `invalid_date_range`: date_start is later than date_end, or updated_start is later than updated_end, so the range can never match. `upstream_error`: The CPSC recall service (saferproducts.gov) was unavailable, timed out, or sent an unreadable response. `upstream_rejected`: CPSC rejected the request instead of returning recalls, and it rejects the same request every time. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_date_range",
      -  "no_results",
      -  "upstream_error",
      -  "upstream_rejected"
      -]New value: +[
      +  "missing_criteria",
      +  "invalid_date_range",
      +  "upstream_error",
      +  "upstream_rejected"
      +]
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Present when the page needs explaining: zero matches (with which criterion to relax), an offset past the last match, or a page cut short by the response size budget (with the offset to continue from).",
      +  "type": "string"
      +}
    • changedOutput schema / properties / recalls / items / properties / data_quality_notes / description
      Previous value: -"Gaps this server observed in the upstream CPSC record — absent hazard text, absent product entries. Derived from which fields CPSC left empty, not from any judgement about the recall itself. Empty when nothing is missing."New value: +"Gaps this server observed in the CPSC record — absent hazard text, absent product entries. Derived from which fields CPSC left empty, not from any judgement about the recall itself. Empty when nothing is missing."
    • changedOutput schema / properties / recalls / items / properties / data_quality_notes / items / description
      Previous value: -"One gap found in the upstream record."New value: +"One gap found in the CPSC record."
    • changedOutput schema / properties / recalls / items / properties / upcs / description
      Previous value: -"UPC codes for this recall (sparse — ~4% of records have UPCs). UPCs are stored at the recall level in the API, not per-product; when a recall covers multiple products, all UPCs apply to the recall as a whole."New value: +"UPC codes for this recall (sparse — ~4% of records have UPCs). CPSC lists UPCs for the recall as a whole, not per product, so on a recall covering several products a UPC cannot be tied to one of them."
    • changedOutput schema / properties / total_found / description
      Previous value: -"Total matching records, counted after hazard_search is applied and before offset and limit narrow the window."New value: +"Total matching records, counted after every filter is applied and before offset, limit, and the response size budget narrow the window."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when total_found exceeds the limit. Independent of offset."New value: +"True when matching records remain past this page — always equal to has_more."
  4. Changed1 schema field changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: date_start is later than date_end, or updated_start is later than updated_end, so the range can never match `no_results`: No recalls matched the search filters, including hazard_search `upstream_error`: The saferproducts.gov API returned a transient error or timed out `upstream_rejected`: The saferproducts.gov API answered with an error row instead of recall records, which the same request will always produce Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: date_start is later than date_end, or updated_start is later than updated_end, so the range can never match. `no_results`: No recalls matched the search filters, including hazard_search. `upstream_error`: The saferproducts.gov API returned a transient error or timed out. `upstream_rejected`: The saferproducts.gov API answered with an error row instead of recall records, which the same request will always produce. Other values are possible when a failure originates below the handler."
  5. 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": [
      +      "recalls",
      +      "total_found",
      +      "truncated",
      +      "offset",
      +      "has_more",
      +      "cpsc_jurisdiction",
      +      "source_note"
      +    ]
      +  },
      +  {
      +    "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: `invalid_date_range`: date_start is later than date_end, or updated_start is later than updated_end, so the range can never match `no_results`: No recalls matched the search filters, including hazard_search `upstream_error`: The saferproducts.gov API returned a transient error or timed out `upstream_rejected`: The saferproducts.gov API answered with an error row instead of recall records, which the same request will always produce Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "invalid_date_range",
      +            "no_results",
      +            "upstream_error",
      +            "upstream_rejected"
      +          ],
      +          "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: -[
      -  "recalls",
      -  "total_found",
      -  "truncated",
      -  "offset",
      -  "has_more",
      -  "cpsc_jurisdiction",
      -  "source_note"
      -]
  6. Changed14 schema fields changed
    • changedInput schema / properties / description_search / description
      Previous value: -"Keyword search within the recall Description field only (does not search Title or Hazards text). Use for hazard types like \"fire\", \"choking\", \"burn\", or to find product details not captured in product_name. Note: hazard keywords often appear in the Description field — this is the correct filter for hazard-type searching since the Hazard filter param is non-functional upstream."New value: +"Keyword search within the recall Description field only (does not search Title, Hazards, or remedy text). Use for product details not captured in product_name — model numbers, colors, sale channels. For hazard concepts, prefer hazard_search; for the recall headline, prefer title_search."
    • addedInput schema / properties / distributor
      Added value: +{
      +  "description": "Distributor company name, e.g. \"Walmart\", \"Costco\". Substring match against the Distributors array — a role distinct from retailer and importer, and populated on far fewer records.",
      +  "type": "string"
      +}
    • addedInput schema / properties / hazard_search
      Added value: +{
      +  "description": "Hazard or safety-concept keyword, e.g. \"fire\", \"choking\", \"burn\", \"laceration\". Applied client-side after the upstream fetch. Matches when the term appears in any of: hazard descriptions, product names, or remedy instructions (OR across the three, case-insensitive substring). Use this rather than the upstream Hazard parameter, which CPSC recognizes but never matches.",
      +  "type": "string"
      +}
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "description": "Skip this many matching records before returning results. Combine with limit to page through total_found — e.g. limit 20 with offset 0, 20, 40. An offset at or past total_found returns an empty result set rather than an error.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / remedy
      Added value: +{
      +  "description": "Keyword search within the free-text remedy instructions, e.g. \"repair\", \"refund\", \"firmware update\". Substring match, applied upstream. This searches the remedy narrative, not the structured remedy_options enum — \"repair\" matches records whose remedy_options list only \"Refund\" but whose instructions describe a free repair kit. Combines with the other filters using AND; use hazard_search instead to match remedy text as one of several fields.",
      +  "type": "string"
      +}
    • addedInput schema / properties / title_search
      Added value: +{
      +  "description": "Keyword search within the recall Title, e.g. \"chandelier\", \"space heater\", \"inclined sleeper\". Substring match. CPSC titles name the brand, the product, and the hazard, which makes this the highest-signal single filter for most searches.",
      +  "type": "string"
      +}
    • addedInput schema / properties / updated_end
      Added value: +{
      +  "anyOf": [
      +    {
      +      "const": "",
      +      "type": "string"
      +    },
      +    {
      +      "description": "ISO 8601 date: \"YYYY-MM-DD\".",
      +      "format": "date",
      +      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +      "type": "string"
      +    }
      +  ],
      +  "description": "Include only recalls last published by CPSC on or before this date. ISO 8601 format: \"YYYY-MM-DD\". Must be a real calendar date, and on or after updated_start."
      +}
    • addedInput schema / properties / updated_start
      Added value: +{
      +  "anyOf": [
      +    {
      +      "const": "",
      +      "type": "string"
      +    },
      +    {
      +      "description": "ISO 8601 date: \"YYYY-MM-DD\".",
      +      "format": "date",
      +      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +      "type": "string"
      +    }
      +  ],
      +  "description": "Include only recalls last published by CPSC on or after this date. ISO 8601 format: \"YYYY-MM-DD\". A separate axis from date_start: a 2003 recall re-published in 2025 matches updated_start \"2025-01-01\". Use to answer \"what has CPSC updated recently\". Must be a real calendar date."
      +}
    • addedOutput schema / properties / has_more
      Added value: +{
      +  "description": "True when records remain past this window — call again with offset raised by the number of recalls returned.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / offset
      Added value: +{
      +  "description": "Number of matching records skipped before this window.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / recalls / items / properties / remedy_options / description
      Previous value: -"Remedy types: Refund, Repair, Replace, Dispose, Label, New Instructions. Multiple may apply."New value: +"Remedy types: Refund, Repair, Replace, New Instructions, Dispose, Label, No Remedy Available, Inspect. Multiple may apply. Often empty — CPSC classified the remedy on fewer than half its records; read remedy_summary when this is empty, and cpsc_url when that is empty too."
    • changedOutput schema / properties / total_found / description
      Previous value: -"Total matching records before the limit was applied."New value: +"Total matching records, counted after hazard_search is applied and before offset and limit narrow the window."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when total_found exceeds the limit."New value: +"True when total_found exceeds the limit. Independent of offset."
    • changedOutput schema / required
      Previous value: -[
      -  "recalls",
      -  "total_found",
      -  "truncated",
      -  "cpsc_jurisdiction",
      -  "source_note"
      -]New value: +[
      +  "recalls",
      +  "total_found",
      +  "truncated",
      +  "offset",
      +  "has_more",
      +  "cpsc_jurisdiction",
      +  "source_note"
      +]
  7. Changed8 schema fields changed
    • changedInput schema / properties / date_end / anyOf
      Previous value: -[
      -  {
      -    "const": "",
      -    "type": "string"
      -  },
      -  {
      -    "description": "ISO 8601 date: \"YYYY-MM-DD\".",
      -    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "const": "",
      +    "type": "string"
      +  },
      +  {
      +    "description": "ISO 8601 date: \"YYYY-MM-DD\".",
      +    "format": "date",
      +    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +    "type": "string"
      +  }
      +]
    • changedInput schema / properties / date_end / description
      Previous value: -"Include only recalls on or before this date. ISO 8601 format: \"YYYY-MM-DD\"."New value: +"Include only recalls on or before this date. ISO 8601 format: \"YYYY-MM-DD\". Must be a real calendar date, and on or after date_start."
    • changedInput schema / properties / date_start / anyOf
      Previous value: -[
      -  {
      -    "const": "",
      -    "type": "string"
      -  },
      -  {
      -    "description": "ISO 8601 date: \"YYYY-MM-DD\".",
      -    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "const": "",
      +    "type": "string"
      +  },
      +  {
      +    "description": "ISO 8601 date: \"YYYY-MM-DD\".",
      +    "format": "date",
      +    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +    "type": "string"
      +  }
      +]
    • changedInput schema / properties / date_start / description
      Previous value: -"Include only recalls on or after this date. ISO 8601 format: \"YYYY-MM-DD\"."New value: +"Include only recalls on or after this date. ISO 8601 format: \"YYYY-MM-DD\". Must be a real calendar date — \"2026-02-31\" and \"2026-99-99\" are rejected."
    • addedOutput schema / properties / recalls / items / properties / data_quality_notes
      Added value: +{
      +  "description": "Gaps this server observed in the upstream CPSC record — absent hazard text, absent product entries. Derived from which fields CPSC left empty, not from any judgement about the recall itself. Empty when nothing is missing.",
      +  "items": {
      +    "description": "One gap found in the upstream record.",
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / recalls / items / required
      Previous value: -[
      -  "recall_number",
      -  "recall_date",
      -  "title",
      -  "hazards",
      -  "remedy_options",
      -  "remedy_summary",
      -  "products",
      -  "upcs",
      -  "manufacturers",
      -  "importers",
      -  "retailers",
      -  "cpsc_url",
      -  "images"
      -]New value: +[
      +  "recall_number",
      +  "recall_date",
      +  "title",
      +  "hazards",
      +  "remedy_options",
      +  "remedy_summary",
      +  "products",
      +  "upcs",
      +  "manufacturers",
      +  "importers",
      +  "retailers",
      +  "cpsc_url",
      +  "images",
      +  "data_quality_notes"
      +]
    • addedOutput schema / properties / source_note
      Added value: +{
      +  "description": "Provenance caveat: recall fields are relayed from CPSC unedited and unverified; check cpsc_url before a consumer-facing decision.",
      +  "type": "string"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "recalls",
      -  "total_found",
      -  "truncated",
      -  "cpsc_jurisdiction"
      -]New value: +[
      +  "recalls",
      +  "total_found",
      +  "truncated",
      +  "cpsc_jurisdiction",
      +  "source_note"
      +]
  8. First observed

TDQS

A4.3/5.0
Behavior3/5

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuinely non-derived behavior: page size can shrink below limit due to a 64,000-byte response budget, total_found/has_more drive paging, and an offset past total_found yields an empty set rather than an error. However, most of that is also in the limit/offset schema descriptions, so the incremental disclosure over structured fields is modest rather than exceptional.

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?

Information density is high and the routing constraints are front-loaded, but the whole definition is one ~250-word unstructured paragraph that mixes filtering strategy, pagination mechanics, and jurisdictional boundaries with no visual separation. A reader must parse the entire block to find the pagination rules, and a few clauses (the fire/fireworks and battery/batteries stemming examples) restate the no-stemming rule already made once.

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 15-parameter, zero-required search tool with an output schema, this covers what an agent actually needs: what is searchable, how filters combine, how to page, when the result set is truncated, where to get full records, and which queries belong to other agencies. Return-value shape is correctly left to the output schema.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description lifts this by adding cross-parameter strategy the schema can't express — the soft requirement of at least one filter, that filters AND together, the prioritization of title_search over other text filters, and the manufacturer→importer/retailer/distributor fallback. Some of this repeats the individual parameter descriptions (title_search being 'highest-signal', the manufacturer fallback), which keeps it from a 5.

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 and resource ('Search consumer product recalls from the CPSC') and enumerates the product categories covered, so scope is unambiguous. It explicitly names the sibling cpsc_get_recent as the tool for browsing without filters, and points to cpsc_get_recall for full records, making it distinguishable from both siblings without opening a 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 a hard precondition ('Give at least one text filter or date bound'), an explicit alternative when that precondition doesn't hold (cpsc_get_recent), first-choice filter guidance ('Start with title_search when you have a product in hand'), a hazard-specific alternative (hazard_search), and a fallback chain when manufacturer misses (importer/retailer/distributor). It also states when the tool is the wrong agency entirely (FDA, NHTSA, USCG, EPA, ATF jurisdiction).

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.