{
  "server": {
    "name": "Product.ai MCP",
    "url": "https://mcp.product.ai/mcp",
    "transport": "streamable-http"
  },
  "auth": {
    "oauth_metadata": "https://mcp.product.ai/.well-known/oauth-protected-resource",
    "api_key": {
      "header": "Authorization: Bearer pai_live_...",
      "console": "https://auth.product.ai/account/keys"
    }
  },
  "tools": [
    {
      "name": "axioms_ground",
      "title": "Ground in a category",
      "description": "Get the Truth Pack for one product category before you reason or write about it. A Truth Pack is a short, prompt-ready block of the category's laws from the Product.ai Truth Graph: up to 10 laws, each with its axiom id, its confidence tier (forged = three or more independent research providers converged; probable = two agreed) and its layer, plus up to 4 elimination gates where the category records a falsifier. Pass exactly one of `category` (a slug such as skincare-actives or mattresses; prefixes and plain names resolve) or `topic` (free text, resolved to the closest served category). Packs are pre-built, so this answers fast and makes no model call. If the category is not served you get status not_covered with reason shelf_not_served, and the miss is counted as demand. Use the pack as grounding, cite axiom ids when you rely on a law, and call axioms_check on any specific claim before you assert it to a person. Requires the fact_checking scope.",
      "capability": "Fact checking",
      "scope": "fact_checking",
      "annotations": {
        "title": "Ground in a category",
        "readOnlyHint": true,
        "idempotentHint": true,
        "openWorldHint": false
      },
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "category": {
            "description": "A category slug such as skincare-actives or mattresses. Prefixes and plain names resolve.",
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "topic": {
            "description": "Free text, resolved to the closest served category when no slug matches.",
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          }
        }
      },
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "contract": {
            "type": "string",
            "const": "axioms/1"
          },
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "not_covered",
              "refused"
            ]
          },
          "pack": {
            "type": "object",
            "properties": {
              "pack_id": {
                "type": "string"
              },
              "category": {
                "type": "string"
              },
              "generated_at": {
                "type": "string"
              },
              "corpus_epoch": {
                "type": "string"
              },
              "laws": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "text": {
                      "type": "string"
                    },
                    "tier": {
                      "type": "string",
                      "enum": [
                        "forged",
                        "probable"
                      ]
                    },
                    "layer": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "text",
                    "tier",
                    "layer"
                  ],
                  "additionalProperties": false
                }
              },
              "gates": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "text": {
                      "type": "string"
                    },
                    "tier": {
                      "type": "string",
                      "enum": [
                        "forged",
                        "probable"
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "text",
                    "tier"
                  ],
                  "additionalProperties": false
                }
              },
              "gates_note": {
                "type": "string"
              },
              "use": {
                "type": "string"
              },
              "token_estimate": {
                "type": "number"
              }
            },
            "required": [
              "pack_id",
              "category",
              "generated_at",
              "corpus_epoch",
              "laws",
              "gates",
              "use",
              "token_estimate"
            ],
            "additionalProperties": false
          },
          "resolved": {
            "type": "object",
            "properties": {
              "by": {
                "type": "string",
                "enum": [
                  "slug",
                  "prefix",
                  "alias",
                  "retrieval"
                ]
              },
              "input": {
                "type": "string"
              }
            },
            "required": [
              "by",
              "input"
            ],
            "additionalProperties": false
          },
          "reason": {
            "type": "string"
          },
          "request_shelf": {
            "type": "object",
            "properties": {
              "recorded": {
                "type": "boolean"
              },
              "kind": {
                "type": "string"
              }
            },
            "required": [
              "recorded",
              "kind"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "contract",
          "status"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "axioms_check",
      "title": "Check a claim",
      "description": "Check a factual product claim against the Product.ai Truth Graph and get a grade per atomic claim. Pass exactly one of `claim` (1 to 6000 characters of text), `check_id` (to poll a check you started), `url` or `sku`. Each graded claim carries one of five states: verified, failed_check, not_checkable, checked_not_settled or not_covered, with plain_truth, tier, what_would_change, qualifier, condition and reuse_until. A claim graded before answers at once from an exact-text cache (status graded, source cache). An unchecked claim answers status pending with a check_id and retry_after_ms: grading runs in the background, so poll with that check_id until the status is graded. pending is never a grade, and claims is empty until it is. check_failed means grading failed after retries; resubmit after retry_after_ms. budget_deferred means the day's grade budget is spent. url and sku answer not_covered with reason spec_index_unbuilt today. Builder tier and above. Requires the fact_checking scope.",
      "capability": "Fact checking",
      "scope": "fact_checking",
      "annotations": {
        "title": "Check a claim",
        "readOnlyHint": true,
        "idempotentHint": true,
        "openWorldHint": false
      },
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "claim": {
            "description": "The claim text to grade, 1 to 6000 characters.",
            "type": "string",
            "minLength": 1,
            "maxLength": 6000
          },
          "check_id": {
            "description": "Poll a check you started: the check_id from a pending answer.",
            "type": "string",
            "pattern": "^chk_[0-9a-f]{32}$"
          },
          "url": {
            "description": "A product page URL (https). Answers not_covered today: the spec index is unbuilt.",
            "type": "string",
            "maxLength": 2048
          },
          "sku": {
            "description": "A product SKU. Answers not_covered today: the spec index is unbuilt.",
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "category": {
            "description": "Optional category slug, a hint only. An unknown category is dropped, never a reason to skip grading.",
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          }
        }
      },
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "contract": {
            "type": "string",
            "const": "axioms/1"
          },
          "status": {
            "type": "string",
            "enum": [
              "graded",
              "pending",
              "not_covered",
              "check_failed",
              "budget_deferred",
              "refused"
            ],
            "description": "A transport status of the call, never a claim state."
          },
          "check_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "cache",
              "fresh"
            ]
          },
          "claims": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "number"
                },
                "text": {
                  "type": "string"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "verified",
                    "failed_check",
                    "not_checkable",
                    "checked_not_settled",
                    "not_covered"
                  ]
                },
                "plain_truth": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "tier": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "what_would_change": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "qualifier": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "condition": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "reason": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "recheck_by": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "reuse_until": {
                  "type": "string"
                },
                "graded_at": {
                  "type": "string"
                }
              },
              "required": [
                "index",
                "text",
                "state",
                "plain_truth",
                "tier",
                "what_would_change",
                "qualifier",
                "condition",
                "reason",
                "recheck_by",
                "reuse_until",
                "graded_at"
              ],
              "additionalProperties": false
            },
            "description": "Real grades only. Empty while pending."
          },
          "unresolved": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "number"
                },
                "text": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "const": "check_failed"
                },
                "retry_after_ms": {
                  "type": "number"
                }
              },
              "required": [
                "index",
                "text",
                "status",
                "retry_after_ms"
              ],
              "additionalProperties": false
            }
          },
          "graded_at": {
            "type": "string"
          },
          "reuse_until": {
            "type": "string"
          },
          "retry_after_ms": {
            "type": "number"
          },
          "held": {
            "type": "boolean"
          },
          "reason": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        },
        "required": [
          "contract",
          "status",
          "check_id",
          "source",
          "claims"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "axioms_resolve_checkout",
      "title": "Resolve a checkout",
      "description": "Hand a shopper's merchant question to SimplyCodes, the Product.ai promo-code verifier, and get its verified answer plus a checkout link. Pass `merchant` (a domain such as nike.com, or the merchant's name) and optionally `limit` (1 to 10 offers, default 5). A `sku` alone is not resolved yet and answers status unresolved. The `simplycodes` field is SimplyCodes' own get_merchant_codes answer, unchanged: offers ranked by real checkout tests, a verification capsule, provenance meta, and either a literal code (paid tiers) or a reveal_url (free tier). `checkout_link` is the first offer's reveal_url or store link, copied verbatim; relay it unchanged so attribution survives. `price` is always null: no live merchant price source exists, and price_status says so. SimplyCodes' refusals (keyed_only, rate_capped, access_pending with apply_url, merchant_not_found, principal_suspended, retrieval_failure) come back as errors with its own reason. Requires the promo_codes scope.",
      "capability": "Promo codes",
      "scope": "promo_codes",
      "annotations": {
        "title": "Resolve a checkout",
        "readOnlyHint": true,
        "idempotentHint": false,
        "openWorldHint": true
      },
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "merchant": {
            "description": "The merchant, by domain (nike.com) or name (Nike). Required today.",
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "sku": {
            "description": "A product SKU. Alone, it answers unresolved today.",
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "limit": {
            "description": "How many offers to return, 1 to 10 (default 5).",
            "type": "integer",
            "minimum": 1,
            "maximum": 10
          }
        }
      },
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "contract": {
            "type": "string",
            "const": "axioms/1"
          },
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "refused",
              "unresolved"
            ]
          },
          "simplycodes": {
            "anyOf": [
              {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {}
              },
              {
                "type": "null"
              }
            ]
          },
          "checkout_link": {
            "type": [
              "string",
              "null"
            ]
          },
          "price": {
            "type": "null"
          },
          "price_status": {
            "type": "string",
            "const": "no_live_price_source"
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "contract",
          "status",
          "simplycodes",
          "checkout_link",
          "price",
          "price_status"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "verify_promo_code",
      "title": "Verify one promo code",
      "description": "Check whether one promo code works at a merchant right now and get SimplyCodes' dated verdict. Returns `verdict` (VERIFIED_OK, CONFIDENT_NO, UNTESTED, or WITHHELD), `verified_at`, `ttl_seconds`, the verification capsule, and `channels_observed` for a NO. Use this when a shopper already has a code and asks if it is real; an untested code returns UNTESTED with no guess, never a fabricated verdict.",
      "capability": "Promo codes",
      "scope": "promo_codes",
      "annotations": {
        "title": "Verify one promo code",
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": true
      },
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "merchant": {
            "type": "string",
            "minLength": 2,
            "maxLength": 120,
            "description": "One merchant, by domain (nike.com) or full name (Nike). Required — this tool never answers for a merchant you did not name."
          },
          "promo_code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "The exact promo code to check, as the shopper has it. Case and surrounding spaces are ignored."
          }
        },
        "required": [
          "merchant",
          "promo_code"
        ]
      },
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "merchant": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "domain": {
                "description": "The resolved merchant's primary domain, or null when SimplyCodes has none on record.",
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "id": {
                "description": "SimplyCodes' merchant id (legacy_merchant_id), or null when upstream carries none.",
                "anyOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "name",
              "slug",
              "domain",
              "id"
            ],
            "additionalProperties": false,
            "description": "The merchant this answer is about, as SimplyCodes resolved it. Every key is present; domain and id are null when unknown."
          },
          "tier": {
            "type": "string",
            "enum": [
              "unauthenticated",
              "explorer",
              "builder",
              "pro",
              "scale",
              "enterprise"
            ],
            "description": "The caller's SimplyCodes tier. unauthenticated — no principal resolved (refused). explorer — free, reveal-only. builder — paid, literal codes. pro — paid, literal codes. scale — paid, literal codes. enterprise — paid, literal codes."
          },
          "keyed": {
            "type": "boolean"
          },
          "serving_mode": {
            "type": "string",
            "enum": [
              "literal",
              "reveal"
            ],
            "description": "How this answer was served. literal — offers carry the code string. reveal — offers carry reveal_url and no code field at all."
          },
          "holdout": {
            "type": "boolean"
          },
          "platform_origin": {
            "type": "string",
            "description": "The true origin stamped on every URL in this answer."
          },
          "verdict": {
            "type": "string",
            "enum": [
              "VERIFIED_OK",
              "CONFIDENT_NO",
              "UNTESTED",
              "WITHHELD"
            ],
            "description": "SimplyCodes' dated verdict. VERIFIED_OK — tested at checkout and working. CONFIDENT_NO — tested and NOT working, scoped to channels_observed; a real answer, not a failure. UNTESTED — SimplyCodes has no checkout test for this code, so no claim is made either way. WITHHELD — the merchant resolves but its verification page is not materialized yet, so nothing is asserted."
          },
          "channels_observed": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The channels this verdict actually observed. Never empty — an unscoped no is not a verdict."
          },
          "capsule": {
            "type": "string",
            "description": "The citable verification sentence, composed from this answer's own counts."
          },
          "offers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "description": "The literal promo code. Paid tiers only; absent on the free tier.",
                  "type": "string"
                },
                "code_ref": {
                  "description": "Stable id for this offer — pass it back to report_code_outcome. Null when SimplyCodes has no stable id for it, in which case there is nothing to report against.",
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "title": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "offer_type": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "percent_off": {
                  "type": "number"
                },
                "amount_off": {
                  "type": "number"
                },
                "storewide": {
                  "type": "boolean"
                },
                "minimum_spend_cents": {
                  "type": "number"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "green",
                    "yellow",
                    "red",
                    "untested"
                  ],
                  "description": "Upstream validity flag for this offer. green — last checkout test succeeded. yellow — tested with mixed or low-confidence results. red — last checkout test failed. untested — no checkout test on record."
                },
                "verified": {
                  "type": "boolean",
                  "description": "True only when the last checkout test succeeded AND a literal exists."
                },
                "confidence": {
                  "type": "number"
                },
                "success_rate": {
                  "description": "Share of SimplyCodes checkout attempts that succeeded.",
                  "type": "number"
                },
                "attempts": {
                  "type": "number"
                },
                "checkout_tests": {
                  "type": "number"
                },
                "success_score": {
                  "type": "number"
                },
                "days_since_last_success": {
                  "type": "number"
                },
                "last_verified_at": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "ends_on": {
                  "type": "string"
                },
                "exclusive": {
                  "type": "boolean"
                },
                "success_rate_by_channel": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": "number"
                  }
                },
                "store_url": {
                  "type": "string",
                  "description": "Origin-stamped merchant page link. Relay it unchanged."
                },
                "reveal_url": {
                  "description": "Free tier: where the shopper reveals the code. Relay it unchanged.",
                  "type": "string"
                }
              },
              "required": [
                "code_ref",
                "status",
                "verified",
                "store_url"
              ],
              "additionalProperties": false,
              "description": "One verified offer. On the free tier the literal code is absent and reveal_url is present."
            },
            "description": "Verified offers in upstream ranking order. Empty array, never omitted."
          },
          "caveats": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Honest qualifiers: stale_upstream, not_yet_materialized, unverified_codes (listed codes have no passing test), page_truncated (the read stopped at the row ceiling, so counts are floors and absence is not absence), projection_drift (part of the page used a status vocabulary this service does not know), projection_mismatch (upstream served a page this service could not read), merchant_mismatch (upstream resolved a different merchant than the one asked for; nothing is asserted), verified_at_unknown (no verification stamp exists upstream), duplicate_code_rows (several catalogue rows carry the requested code), merchant_identity_unverified (the page carries no identity to confirm the merchant; no CONFIDENT_NO is published), merchant ambiguity."
          },
          "meta": {
            "type": "object",
            "properties": {
              "verified_at": {
                "description": "ISO-8601 stamp of the newest verification signal behind this answer, or null when SimplyCodes holds none (never the read time; the verified_at_unknown caveat rides a null).",
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "ttl_seconds": {
                "anyOf": [
                  {
                    "type": "integer",
                    "exclusiveMinimum": 0,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "string",
                    "const": "unmeasured"
                  }
                ],
                "description": "How long this read stays defensible, from observed signal ages, or the string unmeasured. Never a default."
              },
              "expected_decay_rate": {
                "anyOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "string",
                    "const": "unmeasured"
                  }
                ],
                "description": "Observed share of verdicts going stale per day, or the string unmeasured."
              },
              "freshness": {
                "type": "string",
                "enum": [
                  "measured",
                  "unmeasured",
                  "stale"
                ],
                "description": "How the freshness numbers were obtained. measured — ttl_seconds and expected_decay_rate come from observed signal ages. unmeasured — upstream carried no signal ages, so no cadence is claimed rather than a default being invented. stale — the upstream materialization is behind its own schedule; treat the verdict as dated, not current."
              },
              "source": {
                "type": "string",
                "const": "simplycodes_scssl",
                "description": "The serving layer this answer was read from."
              },
              "methodology_url": {
                "type": "string",
                "description": "Where the verification methodology is published, for citation."
              },
              "attribution_guidance": {
                "type": "string",
                "description": "What to preserve when relaying this answer, so attribution survives."
              },
              "comparability": {
                "type": "string",
                "description": "What the rates in this answer are, and what they are not."
              },
              "generated_at": {
                "type": "string",
                "description": "ISO-8601 stamp of when this response was composed."
              }
            },
            "required": [
              "verified_at",
              "ttl_seconds",
              "expected_decay_rate",
              "freshness",
              "source",
              "methodology_url",
              "attribution_guidance",
              "comparability",
              "generated_at"
            ],
            "additionalProperties": false,
            "description": "The provenance envelope. Exactly these keys: verified_at, ttl_seconds, expected_decay_rate, freshness, source, methodology_url, attribution_guidance, comparability, generated_at."
          },
          "code_ref": {
            "description": "Stable id of the matched offer, or null when the code is not in SimplyCodes' catalogue.",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "merchant",
          "tier",
          "keyed",
          "serving_mode",
          "platform_origin",
          "verdict",
          "channels_observed",
          "capsule",
          "offers",
          "caveats",
          "meta",
          "code_ref"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "get_merchant_codes",
      "title": "Get verified codes for one merchant",
      "description": "Get the promo codes SimplyCodes has verified as working at one merchant, ranked by success rate. Returns `offers` with success counts and last-verified dates, a `capsule` stating what was tested, and either a literal `code` on paid tiers or a `reveal_url` on the free tier. Use this when a shopper is about to check out at a named merchant; it never lists codes for merchants you did not name.",
      "capability": "Promo codes",
      "scope": "promo_codes",
      "annotations": {
        "title": "Get verified codes for one merchant",
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": true
      },
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "merchant": {
            "type": "string",
            "minLength": 2,
            "maxLength": 120,
            "description": "One merchant, by domain (nike.com) or full name (Nike). Required — this tool never answers for a merchant you did not name."
          },
          "limit": {
            "default": 10,
            "description": "How many verified offers to return, 1 to 20. Defaults to 10. This bounds one merchant, not a merchant walk.",
            "type": "integer",
            "minimum": 1,
            "maximum": 20
          }
        },
        "required": [
          "merchant"
        ]
      },
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "merchant": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "domain": {
                "description": "The resolved merchant's primary domain, or null when SimplyCodes has none on record.",
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "id": {
                "description": "SimplyCodes' merchant id (legacy_merchant_id), or null when upstream carries none.",
                "anyOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "name",
              "slug",
              "domain",
              "id"
            ],
            "additionalProperties": false,
            "description": "The merchant this answer is about, as SimplyCodes resolved it. Every key is present; domain and id are null when unknown."
          },
          "tier": {
            "type": "string",
            "enum": [
              "unauthenticated",
              "explorer",
              "builder",
              "pro",
              "scale",
              "enterprise"
            ],
            "description": "The caller's SimplyCodes tier. unauthenticated — no principal resolved (refused). explorer — free, reveal-only. builder — paid, literal codes. pro — paid, literal codes. scale — paid, literal codes. enterprise — paid, literal codes."
          },
          "keyed": {
            "type": "boolean"
          },
          "serving_mode": {
            "type": "string",
            "enum": [
              "literal",
              "reveal"
            ],
            "description": "How this answer was served. literal — offers carry the code string. reveal — offers carry reveal_url and no code field at all."
          },
          "holdout": {
            "type": "boolean"
          },
          "platform_origin": {
            "type": "string",
            "description": "The true origin stamped on every URL in this answer."
          },
          "verdict": {
            "type": "string",
            "enum": [
              "VERIFIED_OK",
              "CONFIDENT_NO",
              "UNTESTED",
              "WITHHELD"
            ],
            "description": "SimplyCodes' dated verdict. VERIFIED_OK — tested at checkout and working. CONFIDENT_NO — tested and NOT working, scoped to channels_observed; a real answer, not a failure. UNTESTED — SimplyCodes has no checkout test for this code, so no claim is made either way. WITHHELD — the merchant resolves but its verification page is not materialized yet, so nothing is asserted."
          },
          "channels_observed": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The channels this verdict actually observed. Never empty — an unscoped no is not a verdict."
          },
          "capsule": {
            "type": "string",
            "description": "The citable verification sentence, composed from this answer's own counts."
          },
          "offers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "description": "The literal promo code. Paid tiers only; absent on the free tier.",
                  "type": "string"
                },
                "code_ref": {
                  "description": "Stable id for this offer — pass it back to report_code_outcome. Null when SimplyCodes has no stable id for it, in which case there is nothing to report against.",
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "title": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "offer_type": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "percent_off": {
                  "type": "number"
                },
                "amount_off": {
                  "type": "number"
                },
                "storewide": {
                  "type": "boolean"
                },
                "minimum_spend_cents": {
                  "type": "number"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "green",
                    "yellow",
                    "red",
                    "untested"
                  ],
                  "description": "Upstream validity flag for this offer. green — last checkout test succeeded. yellow — tested with mixed or low-confidence results. red — last checkout test failed. untested — no checkout test on record."
                },
                "verified": {
                  "type": "boolean",
                  "description": "True only when the last checkout test succeeded AND a literal exists."
                },
                "confidence": {
                  "type": "number"
                },
                "success_rate": {
                  "description": "Share of SimplyCodes checkout attempts that succeeded.",
                  "type": "number"
                },
                "attempts": {
                  "type": "number"
                },
                "checkout_tests": {
                  "type": "number"
                },
                "success_score": {
                  "type": "number"
                },
                "days_since_last_success": {
                  "type": "number"
                },
                "last_verified_at": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "ends_on": {
                  "type": "string"
                },
                "exclusive": {
                  "type": "boolean"
                },
                "success_rate_by_channel": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": "number"
                  }
                },
                "store_url": {
                  "type": "string",
                  "description": "Origin-stamped merchant page link. Relay it unchanged."
                },
                "reveal_url": {
                  "description": "Free tier: where the shopper reveals the code. Relay it unchanged.",
                  "type": "string"
                }
              },
              "required": [
                "code_ref",
                "status",
                "verified",
                "store_url"
              ],
              "additionalProperties": false,
              "description": "One verified offer. On the free tier the literal code is absent and reveal_url is present."
            },
            "description": "Verified offers in upstream ranking order. Empty array, never omitted."
          },
          "caveats": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Honest qualifiers: stale_upstream, not_yet_materialized, unverified_codes (listed codes have no passing test), page_truncated (the read stopped at the row ceiling, so counts are floors and absence is not absence), projection_drift (part of the page used a status vocabulary this service does not know), projection_mismatch (upstream served a page this service could not read), merchant_mismatch (upstream resolved a different merchant than the one asked for; nothing is asserted), verified_at_unknown (no verification stamp exists upstream), duplicate_code_rows (several catalogue rows carry the requested code), merchant_identity_unverified (the page carries no identity to confirm the merchant; no CONFIDENT_NO is published), merchant ambiguity."
          },
          "meta": {
            "type": "object",
            "properties": {
              "verified_at": {
                "description": "ISO-8601 stamp of the newest verification signal behind this answer, or null when SimplyCodes holds none (never the read time; the verified_at_unknown caveat rides a null).",
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "ttl_seconds": {
                "anyOf": [
                  {
                    "type": "integer",
                    "exclusiveMinimum": 0,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "string",
                    "const": "unmeasured"
                  }
                ],
                "description": "How long this read stays defensible, from observed signal ages, or the string unmeasured. Never a default."
              },
              "expected_decay_rate": {
                "anyOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "string",
                    "const": "unmeasured"
                  }
                ],
                "description": "Observed share of verdicts going stale per day, or the string unmeasured."
              },
              "freshness": {
                "type": "string",
                "enum": [
                  "measured",
                  "unmeasured",
                  "stale"
                ],
                "description": "How the freshness numbers were obtained. measured — ttl_seconds and expected_decay_rate come from observed signal ages. unmeasured — upstream carried no signal ages, so no cadence is claimed rather than a default being invented. stale — the upstream materialization is behind its own schedule; treat the verdict as dated, not current."
              },
              "source": {
                "type": "string",
                "const": "simplycodes_scssl",
                "description": "The serving layer this answer was read from."
              },
              "methodology_url": {
                "type": "string",
                "description": "Where the verification methodology is published, for citation."
              },
              "attribution_guidance": {
                "type": "string",
                "description": "What to preserve when relaying this answer, so attribution survives."
              },
              "comparability": {
                "type": "string",
                "description": "What the rates in this answer are, and what they are not."
              },
              "generated_at": {
                "type": "string",
                "description": "ISO-8601 stamp of when this response was composed."
              }
            },
            "required": [
              "verified_at",
              "ttl_seconds",
              "expected_decay_rate",
              "freshness",
              "source",
              "methodology_url",
              "attribution_guidance",
              "comparability",
              "generated_at"
            ],
            "additionalProperties": false,
            "description": "The provenance envelope. Exactly these keys: verified_at, ttl_seconds, expected_decay_rate, freshness, source, methodology_url, attribution_guidance, comparability, generated_at."
          }
        },
        "required": [
          "merchant",
          "tier",
          "keyed",
          "serving_mode",
          "platform_origin",
          "verdict",
          "channels_observed",
          "capsule",
          "offers",
          "caveats",
          "meta"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "get_merchant_verification",
      "title": "Get one merchant's verification record",
      "description": "Get SimplyCodes' verification record for one merchant without any codes: how many public codes were tested, how many worked, the working rate, and when the last test ran. Returns `tested_count`, `working_count`, `working_rate`, `last_verified_at`, `freshness` (measured, unmeasured, or stale), and a citable `capsule`. Use this when the question is whether a merchant's coupons are worth pursuing, or to cite SimplyCodes as the verifier.",
      "capability": "Promo codes",
      "scope": "promo_codes",
      "annotations": {
        "title": "Get one merchant's verification record",
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": true
      },
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "merchant": {
            "type": "string",
            "minLength": 2,
            "maxLength": 120,
            "description": "One merchant, by domain (nike.com) or full name (Nike). Required — this tool never answers for a merchant you did not name."
          }
        },
        "required": [
          "merchant"
        ]
      },
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "merchant": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "domain": {
                "description": "The resolved merchant's primary domain, or null when SimplyCodes has none on record.",
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "id": {
                "description": "SimplyCodes' merchant id (legacy_merchant_id), or null when upstream carries none.",
                "anyOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "name",
              "slug",
              "domain",
              "id"
            ],
            "additionalProperties": false,
            "description": "The merchant this answer is about, as SimplyCodes resolved it. Every key is present; domain and id are null when unknown."
          },
          "tier": {
            "type": "string",
            "description": "The caller's SimplyCodes tier. This tool answers identically on every tier."
          },
          "verdict": {
            "type": "string",
            "enum": [
              "VERIFIED_OK",
              "CONFIDENT_NO",
              "UNTESTED",
              "WITHHELD"
            ],
            "description": "SimplyCodes' dated verdict. VERIFIED_OK — tested at checkout and working. CONFIDENT_NO — tested and NOT working, scoped to channels_observed; a real answer, not a failure. UNTESTED — SimplyCodes has no checkout test for this code, so no claim is made either way. WITHHELD — the merchant resolves but its verification page is not materialized yet, so nothing is asserted."
          },
          "tested_count": {
            "description": "Public codes SimplyCodes has tested at checkout for this merchant.",
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "working_count": {
            "description": "How many of those are working right now.",
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "working_rate": {
            "description": "Working share over the codes SimplyCodes tested — NOT the merchant's redemption rate. Null when unmeasured.",
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "last_verified_at": {
            "description": "When the last checkout test ran, ISO-8601.",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "sensing_coverage_pct": {
            "description": "Share of the merchant's known public catalogue SimplyCodes is currently sensing.",
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "freshness": {
            "type": "string",
            "enum": [
              "measured",
              "unmeasured",
              "stale"
            ],
            "description": "measured — the numbers come from observed signal ages. unmeasured — no cadence is claimed. stale — upstream materialization is behind schedule."
          },
          "capsule": {
            "type": "string",
            "description": "The citable verification sentence, composed from these counts."
          },
          "caveats": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Honest qualifiers: stale_upstream, not_yet_materialized, unverified_codes (listed codes have no passing test), page_truncated (the read stopped at the row ceiling, so counts are floors and absence is not absence), projection_drift (part of the page used a status vocabulary this service does not know), projection_mismatch (upstream served a page this service could not read), merchant_mismatch (upstream resolved a different merchant than the one asked for; nothing is asserted), verified_at_unknown (no verification stamp exists upstream), duplicate_code_rows (several catalogue rows carry the requested code), merchant_identity_unverified (the page carries no identity to confirm the merchant; no CONFIDENT_NO is published), merchant ambiguity."
          },
          "meta": {
            "type": "object",
            "properties": {
              "verified_at": {
                "description": "ISO-8601 stamp of the newest verification signal behind this answer, or null when SimplyCodes holds none (never the read time; the verified_at_unknown caveat rides a null).",
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "ttl_seconds": {
                "anyOf": [
                  {
                    "type": "integer",
                    "exclusiveMinimum": 0,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "string",
                    "const": "unmeasured"
                  }
                ],
                "description": "How long this read stays defensible, from observed signal ages, or the string unmeasured. Never a default."
              },
              "expected_decay_rate": {
                "anyOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "string",
                    "const": "unmeasured"
                  }
                ],
                "description": "Observed share of verdicts going stale per day, or the string unmeasured."
              },
              "freshness": {
                "type": "string",
                "enum": [
                  "measured",
                  "unmeasured",
                  "stale"
                ],
                "description": "How the freshness numbers were obtained. measured — ttl_seconds and expected_decay_rate come from observed signal ages. unmeasured — upstream carried no signal ages, so no cadence is claimed rather than a default being invented. stale — the upstream materialization is behind its own schedule; treat the verdict as dated, not current."
              },
              "source": {
                "type": "string",
                "const": "simplycodes_scssl",
                "description": "The serving layer this answer was read from."
              },
              "methodology_url": {
                "type": "string",
                "description": "Where the verification methodology is published, for citation."
              },
              "attribution_guidance": {
                "type": "string",
                "description": "What to preserve when relaying this answer, so attribution survives."
              },
              "comparability": {
                "type": "string",
                "description": "What the rates in this answer are, and what they are not."
              },
              "generated_at": {
                "type": "string",
                "description": "ISO-8601 stamp of when this response was composed."
              }
            },
            "required": [
              "verified_at",
              "ttl_seconds",
              "expected_decay_rate",
              "freshness",
              "source",
              "methodology_url",
              "attribution_guidance",
              "comparability",
              "generated_at"
            ],
            "additionalProperties": false,
            "description": "The provenance envelope. Exactly these keys: verified_at, ttl_seconds, expected_decay_rate, freshness, source, methodology_url, attribution_guidance, comparability, generated_at."
          }
        },
        "required": [
          "merchant",
          "tier",
          "verdict",
          "tested_count",
          "working_count",
          "working_rate",
          "last_verified_at",
          "sensing_coverage_pct",
          "freshness",
          "capsule",
          "caveats",
          "meta"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "report_code_outcome",
      "title": "Report a code outcome",
      "description": "Report what happened when a shopper used a code SimplyCodes served: worked, failed, expired, or not applicable, with the order value if known. Returns `recorded` (true), the `outcome` as stored, and a `standing_note`. Use this after every checkout attempt; reports are the data payment that keeps free access open, duplicates for the same code on the same day are ignored, and nothing you report raises your cap.",
      "capability": "Promo codes",
      "scope": "promo_codes",
      "annotations": {
        "title": "Report a code outcome",
        "readOnlyHint": false,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": true
      },
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "merchant": {
            "type": "string",
            "minLength": 2,
            "maxLength": 120,
            "description": "The merchant the code was used at, as domain or name — the same identifier you looked it up with."
          },
          "code_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "The `code_ref` SimplyCodes returned with the offer. Not the code string itself."
          },
          "outcome": {
            "type": "string",
            "enum": [
              "worked",
              "failed",
              "expired",
              "not_applicable"
            ],
            "description": "What happened at checkout. worked — the code applied and discounted the order. failed — the code was rejected. expired — the merchant said the code has expired. not_applicable — the shopper never attempted it (wrong cart, changed their mind)."
          },
          "issue": {
            "description": "Why it failed. Send this only with outcome failed; it is the folded code-feedback vote.",
            "type": "string",
            "enum": [
              "expired",
              "minimum_not_met",
              "excluded_items",
              "invalid",
              "other"
            ]
          },
          "order_value": {
            "description": "Order total in the store's currency, if the shopper shared it. Optional, never required.",
            "type": "number",
            "minimum": 0,
            "maximum": 1000000
          },
          "discount_value": {
            "description": "How much the code took off, if known. Optional.",
            "type": "number",
            "minimum": 0,
            "maximum": 1000000
          },
          "notes": {
            "description": "One short human note, 500 characters max. No personal data.",
            "type": "string",
            "maxLength": 500
          }
        },
        "required": [
          "merchant",
          "code_ref",
          "outcome"
        ]
      },
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "recorded": {
            "type": "boolean",
            "description": "True when the report was stored. A refusal returns isError instead."
          },
          "merchant": {
            "type": "string"
          },
          "code_ref": {
            "type": "string"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "worked",
              "failed",
              "expired",
              "not_applicable"
            ],
            "description": "What happened at checkout. worked — the code applied and discounted the order. failed — the code was rejected. expired — the merchant said the code has expired. not_applicable — the shopper never attempted it (wrong cart, changed their mind)."
          },
          "issue": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "received_at": {
            "type": "string",
            "description": "ISO-8601 stamp of when SimplyCodes stored this report."
          },
          "standing_note": {
            "type": "string",
            "description": "What this report does and does not buy you. Reporting keeps the free lane open; it never raises a cap."
          }
        },
        "required": [
          "recorded",
          "merchant",
          "code_ref",
          "outcome",
          "issue",
          "received_at",
          "standing_note"
        ],
        "additionalProperties": false
      }
    }
  ]
}