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 asparams.arguments of tools/call. Unknown keys are rejected with invalid_input.
string
required
A product or brand name the person asked about. At least two characters.Max length 60.
string
The person’s completed scan. Required unless this deployment allows anonymous lookups.Format
uuid.string
Pattern
^[a-f0-9]{64}$.Output
Returned asstructuredContent, and as the same object serialised in content[0].text. On failure the result has isError: true and an error body instead.
object[]
required
Max 3 items.
Show item
Show item
string
required
string
required
string | null
required
string | null
required
integer | null
required
Range 0–100.
string[]
required
Max 6 items.
string[]
required
Max 6 items.
string[]
required
Max 5 items.
object
required
string | null
required
string | null
required
Format
uri.string | null
required
Format
uri.string | null
required
Format
uri.boolean
required
object
required
string
required
Description the model receives
Description the model receives
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.
Input JSON Schema
Input JSON Schema
{
"$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
}
Output JSON Schema
Output JSON Schema
{
"$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
}
{
"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>" }
}
}
{
"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. …"
}