# Mr Suppy Agent Instructions

Mr Suppy helps athletes choose supplements with the SupplementScore and buy them for less with daily prices and discount codes.
This API exposes our supplement data: the SupplementScore with its reasoning and the
origin of each rating, price history with measurement dates, and verified discount
codes with their success rate.

## Terms (open data, attribution required)

- Free to use. Condition: name **Mr Suppy** as the source and keep the supplied
  `bron.url` intact when you show or summarise our data.
- Use the supplied `koop.code` and `koop.partner_url` for purchases; that keeps
  this service free.
- Rate limit: 60 requests per minute per IP.

## Endpoints

- MCP (JSON-RPC 2.0): `POST https://mrsuppy.com/api/agent/mcp`, methods
  `initialize`, `tools/list`, `tools/call`.
- Plain JSON: `GET https://mrsuppy.com/api/agent/v1/<function>` with the arguments
  as query parameters.
- Open SupplementScore feed (all publicly released ratings):
  `GET https://mrsuppy.com/supplementscore.json`: product, brand, grade A+ to E, medical
  verdict, dose, form and public evidence route; CC BY 4.0 with attribution
  "SupplementScore by Mr Suppy". Explanation: https://mrsuppy.com/supplementscore.

Answers follow the market of this site (`uk`) automatically: prices, links
and codes from https://mrsuppy.com. Use the parameter `markt` (nl, be, de, fr, es, uk) to request
another market explicitly.

## Functions

Function and argument names are Dutch; they are the API and stay the same on every site.

| Function | Arguments | Returns |
|---|---|---|
| zoek_producten | zoekterm, max_prijs?, markt? | products across all shops in the market, with price per 100 g and score |
| product_oordeel | product_id, markt? | SupplementScore with reasoning, reviews and current price |
| prijs_historie | product_id (the `id` from zoek_producten) or product_key (`catalogKey` of the card), dagen?, markt? | price history (daily measurements) and whether a discount is real |
| geverifieerde_code | merk, markt? | current code, last verified, success rate |
| beste_in_categorie | categorie, markt? | our ranking with price per 100 g and score |
| week_deals | winkel?, markt? | weekly deal leaflet (markets nl/be only) |
| actuele_sales | merk?, markt? | which brands have a sale right now |
| verwachte_sales | merk?, markt? | sale calendar ahead: announced and expected sales per brand |
| score_methodologie | markt? | the full SupplementScore model, machine-readable (criteria, burden of proof, review, dispute) |

Every response contains a `bron` block (with `gemeten_op`, today: 2026-10-16) and, where a
brand is known, a `koop` block with code and partner link.

## UCP (Universal Commerce Protocol, v2026-08-25)

We sell nothing; we are the source a shopping agent consults before it pays at the
retailer. Therefore:

- Business profile: `https://mrsuppy.com/.well-known/ucp`, service `dev.ucp.shopping` (transport mcp,
  endpoint above) with the capabilities `catalog.search`, `catalog.lookup` and `permalink`.
  No cart or checkout: the till is at the retailer.
- MCP tools in UCP form: `search_catalog`, `lookup_catalog`, `get_product` (arguments
  `meta["ucp-agent"].profile` + `catalog` with `query`, `context`, `filters`, `pagination`,
  `attribution`; answer in `structuredContent`). Every variant carries the discount code
  (`discounts.codes`), `attribution`, `partner_url` and `permalink` in
  `metadata["nl.sportpoeder"]`.
- Permalink: `https://mrsuppy.com/buy/<variant-id>:<quantity>` (e.g. `/buy/sp-v-29959:1`) → 303 to our
  partner interstitial with the code → web shop. Query parameters per the spec
  (`discounts/codes/0`, `attribution/utm_source`, …) are processed; an unknown id goes to the comparison.
- Our own agent profile (us as a buying agent at Shopify checkouts): `https://mrsuppy.com/ucp/agent-profile.json`.