> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skinai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# find_product

> Look up a named product or brand, scored against the scan.

Searches product names and brands for a product or brand the person named, and returns up to 3 matches. Each result carries the person's `match_score` for their scan.

A completed scan is required (`run_id` and `access_token`). Without one the tool returns `scan_required`. No prices, stock or retailer links are returned.

**Allowance:** 3 lookups per scan. A lookup that finds nothing is not counted. When the allowance is spent the tool succeeds with `products: []` and `entitlement.upgrade_required: true`, so check that field before saying nothing matched.

**Common errors:** `scan_required`, `scan_not_ready`, `not_found`, `catalog_unavailable`, `rate_limited`.

|             |                                                                      |
| ----------- | -------------------------------------------------------------------- |
| Tool        | `find_product`                                                       |
| Listed on   | `/mcp` (guest) and `/mcp/account` (OAuth)                            |
| Annotations | `readOnlyHint: false` `destructiveHint: false` `openWorldHint: true` |

## Input

Sent as `params.arguments` of `tools/call`. Unknown keys are rejected with `invalid_input`.

<ParamField body="query" type="string" required>
  A product or brand name the person asked about. At least two characters.

  Max length 60.
</ParamField>

<ParamField body="run_id" type="string">
  The person's completed scan. Required unless this deployment allows anonymous lookups.

  Format `uuid`.
</ParamField>

<ParamField body="access_token" type="string">
  Pattern `^[a-f0-9]{64}$`.
</ParamField>

## Output

Returned as `structuredContent`, and as the same object serialised in `content[0].text`. On failure the result has `isError: true` and an [error body](/errors) instead.

<ResponseField name="products" type="object[]" required>
  Max 3 items.

  <Expandable title="item">
    <ResponseField name="product_id" type="string" required />

    <ResponseField name="name" type="string" required />

    <ResponseField name="brand" type="string | null" required />

    <ResponseField name="product_type" type="string | null" required />

    <ResponseField name="match_score" type="integer | null" required>
      Range 0–100.
    </ResponseField>

    <ResponseField name="targets" type="string[]" required>
      Max 6 items.
    </ResponseField>

    <ResponseField name="matches_concerns" type="string[]" required>
      Max 6 items.
    </ResponseField>

    <ResponseField name="key_ingredients" type="string[]" required>
      Max 5 items.
    </ResponseField>

    <ResponseField name="attributes" type="object" required>
      <Expandable title="properties">
        <ResponseField name="vegan" type="boolean | null" required />

        <ResponseField name="cruelty_free" type="boolean | null" required />

        <ResponseField name="fragrance_free" type="boolean | null" required />

        <ResponseField name="alcohol_free" type="boolean | null" required />

        <ResponseField name="fungal_acne_safe" type="boolean | null" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="country" type="string | null" required />

    <ResponseField name="image_url" type="string | null" required>
      Format `uri`.
    </ResponseField>

    <ResponseField name="product_url" type="string | null" required>
      Format `uri`.
    </ResponseField>

    <ResponseField name="buy_url" type="string | null" required>
      Format `uri`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="scored_against_scan" type="boolean" required />

<ResponseField name="entitlement" type="object" required>
  <Expandable title="properties">
    <ResponseField name="tier" type="&#x22;free_guest&#x22;" required />

    <ResponseField name="used" type="integer" required>
      Range 0–9007199254740991.
    </ResponseField>

    <ResponseField name="included" type="integer" required>
      Range 0–9007199254740991.
    </ResponseField>

    <ResponseField name="remaining" type="integer" required>
      Range 0–9007199254740991.
    </ResponseField>

    <ResponseField name="upgrade_required" type="boolean" required />

    <ResponseField name="more_in_app" type="string" required />
  </Expandable>
</ResponseField>

<ResponseField name="limitations" type="string" required />

<AccordionGroup>
  <Accordion title="Description the model receives">
    ```text theme={null}
    Look up a specific skincare product or brand the person named, in Skan's catalog. Requires a completed scan: pass its run_id and access_token, and the result carries that person's Skan match percentage alongside the product name, brand, what it targets and its key ingredients. Without a scan this returns scan_required. Prices, stock and retailer availability are not returned; do not state or estimate a price. The free guest allowance is three lookups per scan; when entitlement.upgrade_required is true, point the person to the Skan app. Completes in one call.
    ```
  </Accordion>

  <Accordion title="Input JSON Schema">
    ```json theme={null}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "maxLength": 60,
          "description": "A product or brand name the person asked about. At least two characters."
        },
        "run_id": {
          "description": "The person's completed scan. Required unless this deployment allows anonymous lookups.",
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "access_token": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        }
      },
      "required": [
        "query"
      ],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Output JSON Schema">
    ```json theme={null}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "products": {
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "product_id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "brand": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "product_type": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "match_score": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "targets": {
                "maxItems": 6,
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "matches_concerns": {
                "maxItems": 6,
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "key_ingredients": {
                "maxItems": 5,
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "attributes": {
                "type": "object",
                "properties": {
                  "vegan": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "cruelty_free": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "fragrance_free": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "alcohol_free": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "fungal_acne_safe": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  }
                },
                "required": [
                  "vegan",
                  "cruelty_free",
                  "fragrance_free",
                  "alcohol_free",
                  "fungal_acne_safe"
                ],
                "additionalProperties": false
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "image_url": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "uri"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "product_url": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "uri"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "buy_url": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "uri"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "product_id",
              "name",
              "brand",
              "product_type",
              "match_score",
              "targets",
              "matches_concerns",
              "key_ingredients",
              "attributes",
              "country",
              "image_url",
              "product_url",
              "buy_url"
            ],
            "additionalProperties": false
          }
        },
        "scored_against_scan": {
          "type": "boolean"
        },
        "entitlement": {
          "type": "object",
          "properties": {
            "tier": {
              "type": "string",
              "const": "free_guest"
            },
            "used": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "included": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "remaining": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "upgrade_required": {
              "type": "boolean"
            },
            "more_in_app": {
              "type": "string"
            }
          },
          "required": [
            "tier",
            "used",
            "included",
            "remaining",
            "upgrade_required",
            "more_in_app"
          ],
          "additionalProperties": false
        },
        "limitations": {
          "type": "string"
        }
      },
      "required": [
        "products",
        "scored_against_scan",
        "entitlement",
        "limitations"
      ],
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

<RequestExample>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0", "id": 5, "method": "tools/call",
    "params": {
      "name": "find_product",
      "arguments": { "query": "CeraVe", "run_id": "db56607f-edeb-47f3-bc5d-812d7af19adb", "access_token": "<access_token>" }
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response (structuredContent, first product shown) theme={null}
  {
    "products": [
      {
        "product_id": "products_v2:832",
        "name": "Mineral Sunscreen Stick SPF 50",
        "brand": "CeraVe",
        "product_type": "Sunscreen",
        "match_score": 86,
        "targets": ["hydration", "soothing", "acne and pores", "antioxidant support"],
        "matches_concerns": ["soothing"],
        "key_ingredients": ["Ceramide NP", "Ceramide AP", "Ceramide EOP"],
        "attributes": { "vegan": false, "cruelty_free": false, "fragrance_free": false, "alcohol_free": true, "fungal_acne_safe": false },
        "country": "United States",
        "image_url": "https://imagedelivery.net/…/200125/public",
        "product_url": null,
        "buy_url": null
      }
    ],
    "scored_against_scan": true,
    "entitlement": { "tier": "free_guest", "used": 1, "included": 3, "remaining": 2, "upgrade_required": false, "more_in_app": "…" },
    "limitations": "Catalog information about a product the person asked for. …"
  }
  ```
</ResponseExample>