BeautySpark

Working · 115 ms Security A

io.github.ThomasFindlay/beautyspark-mcpv1.0.0 GitHub verified

BeautySpark MCP server for ChatGPT, Claude and other MCP clients

Local Services

Watch Source

Registry entry

Open in the registry

{
  "_meta": {
    "io.modelcontextprotocol.registry/official": {
      "status": "active",
      "isLatest": true,
      "updatedAt": "2026-11-05T21:05:13.234568Z",
      "publishedAt": "2026-11-05T21:05:13.234568Z",
      "statusChangedAt": "2026-11-05T21:05:13.234568Z"
    }
  },
  "server": {
    "name": "io.github.ThomasFindlay/beautyspark-mcp",
    "title": "BeautySpark",
    "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
    "remotes": [
      {
        "url": "https://mcp.beautyspark.me/mcp",
        "type": "streamable-http"
      }
    ],
    "version": "1.0.0",
    "repository": {
      "url": "https://github.com/ThomasFindlay/beautyspark",
      "source": "github",
      "subfolder": "apps/mcp"
    },
    "description": "BeautySpark MCP server for ChatGPT, Claude and other MCP clients"
  }
}

Maintained by@ThomasFindlay(verified)Also a maintainer?

Try it

Call this server's tools from your browser. Nothing to install.

https://mcp.beautyspark.me/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

check_product_for_season Read-only

Looks a product (and optional shade) up in BeautySpark's season picks. Returns the seasons it is recommended for, or match: null when BeautySpark has not reviewed it; then do not present any verdict as BeautySpark's. Pass season to also get that season's palette for comparison.

productstring, required

Brand and product name, e.g. "ILIA Overglaze".

shadestring

Shade name, e.g. "Flambé".

localestring

The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English.

seasonstring

Color season, e.g. "True Winter" or "true_winter". One of the 12 seasons.

Install

Pick your client. Values in capitals, like YOUR_TOKEN, are yours to fill in.

One click: Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Run in a terminal

claude mcp add --transport http beautyspark-mcp https://mcp.beautyspark.me/mcp

Tools (22)

check_product_for_season

read-only

Argument	Type	Description
shade	string	Shade name, e.g. "Flambé".
locale	string	The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English.
season	string	Color season, e.g. "True Winter" or "true_winter". One of the 12 seasons.
product*	string	Brand and product name, e.g. "ILIA Overglaze".

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "product"
  ],
  "properties": {
    "shade": {
      "type": "string",
      "maxLength": 100,
      "description": "Shade name, e.g. \"Flambé\"."
    },
    "locale": {
      "type": "string",
      "maxLength": 35,
      "description": "The user's language as a language tag, e.g. \"de\" or \"pt-BR\". Set it from the user's language. Defaults to English."
    },
    "season": {
      "type": "string",
      "maxLength": 40,
      "description": "Color season, e.g. \"True Winter\" or \"true_winter\". One of the 12 seasons."
    },
    "product": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Brand and product name, e.g. \"ILIA Overglaze\"."
    }
  }
}

confirm_look_generation

Start the try-on prepared by try_look_from_photo. This spends the BeautySpark credits it quoted. The try-on widget calls it when the user presses Confirm. If no widget is showing, ask the user to confirm the cost first and call it only after they agree. Calling it again for the same quote returns the same job without charging again. If it answers conflict, the same quote is still being confirmed: call it again in a few seconds.

destructive

Argument	Type	Description
quoteId*	string	The quoteId from try_look_from_photo.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "quoteId"
  ],
  "properties": {
    "quoteId": {
      "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)$",
      "description": "The quoteId from try_look_from_photo."
    }
  }
}

create_upload_url

Used by the try-on widget to upload a photo the user picked. Returns an upload URL valid for 15 minutes.

Argument	Type	Description
contentType*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "contentType"
  ],
  "properties": {
    "contentType": {
      "enum": [
        "image/jpeg",
        "image/png",
        "image/webp"
      ],
      "type": "string"
    }
  }
}

delete_my_look

Delete a saved look from the user's BeautySpark My Looks. The look is removed.

destructive

Argument	Type	Description
id*	string	A saved look id from search_my_looks.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "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)$",
      "description": "A saved look id from search_my_looks."
    }
  }
}

fetch

For research modes (deep research, company knowledge). In chat, use get_guide instead. Returns the full text of one item from search: a guide section ("<locale>/<slug>#<anchor>"), an article look ("look:<id>") or a colour-season palette page ("season:<season>").

read-only

Argument	Type	Description
id*	string	An id returned by search.
locale	string	The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 400,
      "minLength": 1,
      "description": "An id returned by search."
    },
    "locale": {
      "type": "string",
      "maxLength": 35,
      "description": "The user's language as a language tag, e.g. \"de\" or \"pt-BR\". Set it from the user's language. Defaults to English."
    }
  }
}

find_article_looks

Find makeup looks shown in BeautySpark articles, filtered by color season, article type and words. With a season, looks made for that season come first; general looks (no season) follow and are labelled. Returns look ids for get_article_look and the article URL to cite.

read-only

Argument	Type	Description
type	string	Article type.
limit	integer
query	string	Words to match against the look title, tags and image description, e.g. "smoky", "graphic liner".
locale	string	The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English.
season	string	Color season, e.g. "True Winter" or "true_winter". One of the 12 seasons.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "type": {
      "enum": [
        "guide",
        "tutorial",
        "season",
        "tool",
        "product",
        "trend"
      ],
      "type": "string",
      "description": "Article type."
    },
    "limit": {
      "type": "integer",
      "default": 6,
      "maximum": 10,
      "minimum": 1
    },
    "query": {
      "type": "string",
      "maxLength": 200,
      "description": "Words to match against the look title, tags and image description, e.g. \"smoky\", \"graphic liner\"."
    },
    "locale": {
      "type": "string",
      "maxLength": 35,
      "description": "The user's language as a language tag, e.g. \"de\" or \"pt-BR\". Set it from the user's language. Defaults to English."
    },
    "season": {
      "type": "string",
      "maxLength": 40,
      "description": "Color season, e.g. \"True Winter\" or \"true_winter\". One of the 12 seasons."
    }
  }
}

get_article_look

Get the steps and shades of one makeup look from a BeautySpark article. The id is a look id returned by find_article_looks ("/images/blog/<article-slug>/<look-name>").

read-only

Argument	Type	Description
id*	string	A look id from find_article_looks, e.g. "/images/blog/<article-slug>/<look-name>".
locale	string	The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "A look id from find_article_looks, e.g. \"/images/blog/<article-slug>/<look-name>\"."
    },
    "locale": {
      "type": "string",
      "maxLength": 35,
      "description": "The user's language as a language tag, e.g. \"de\" or \"pt-BR\". Set it from the user's language. Defaults to English."
    }
  }
}

get_color_season

BeautySpark's palette for one of the 12 color seasons: best, neutral and avoid colors with hex codes, plus the eye makeup and lips & cheeks advice from the season guide. Cite the returned URLs.

read-only

Argument	Type	Description
locale	string	The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English.
season*	string	Color season, e.g. "True Winter" or "true_winter". One of the 12 seasons.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "season"
  ],
  "properties": {
    "locale": {
      "type": "string",
      "maxLength": 35,
      "description": "The user's language as a language tag, e.g. \"de\" or \"pt-BR\". Set it from the user's language. Defaults to English."
    },
    "season": {
      "type": "string",
      "maxLength": 40,
      "description": "Color season, e.g. \"True Winter\" or \"true_winter\". One of the 12 seasons."
    }
  }
}

get_guide

Read one section of a BeautySpark guide in full, by an id from search_guides. Also lists the ids and headings of the other sections of the same article. Cite the returned url.

read-only

Argument	Type	Description
id*	string	A section id returned by search_guides, e.g. "en/how-to-find-your-undertone#intro".

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 400,
      "minLength": 1,
      "description": "A section id returned by search_guides, e.g. \"en/how-to-find-your-undertone#intro\"."
    }
  }
}

get_look_status

Check a try-on started by confirm_look_generation. Waits up to waitSeconds (at most 25) for it to finish before answering. When completed, the result includes the image URL and, when the look has them, its step-by-step instructions with the colours for each step.

read-only

Argument	Type	Description
jobId*	string	The jobId from confirm_look_generation.
waitSeconds	number	Seconds to wait for completion before answering, 0 to 25. Use 25.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "jobId"
  ],
  "properties": {
    "jobId": {
      "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)$",
      "description": "The jobId from confirm_look_generation."
    },
    "waitSeconds": {
      "type": "number",
      "description": "Seconds to wait for completion before answering, 0 to 25. Use 25."
    }
  }
}

get_my_look

Get one saved look in full: steps, products and shades, tags, categories, notes, photos and a link to open it in BeautySpark.

read-only

Argument	Type	Description
id*	string	A saved look id from search_my_looks.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "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)$",
      "description": "A saved look id from search_my_looks."
    }
  }
}

get_my_profile

The user's BeautySpark analysis: color season, undertone, eye shape, face shape and app language. Fields are null until the selfie analysis has been run in the app.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

get_product_picks

BeautySpark's top product pick per category (blush, highlighter, eyeliner, lipstick, lip gloss, bronzer, eyeshadow palette) for a color season, each with the reason and the article it comes from.

read-only

Argument	Type	Description
locale	string	The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English.
season*	string	Color season, e.g. "True Winter" or "true_winter". One of the 12 seasons.
category	string	Only return picks of this category.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "season"
  ],
  "properties": {
    "locale": {
      "type": "string",
      "maxLength": 35,
      "description": "The user's language as a language tag, e.g. \"de\" or \"pt-BR\". Set it from the user's language. Defaults to English."
    },
    "season": {
      "type": "string",
      "maxLength": 40,
      "description": "Color season, e.g. \"True Winter\" or \"true_winter\". One of the 12 seasons."
    },
    "category": {
      "enum": [
        "blush",
        "highlighter",
        "eyeliner",
        "lipstick",
        "lip_gloss",
        "bronzer",
        "eyeshadow_palette"
      ],
      "type": "string",
      "description": "Only return picks of this category."
    }
  }
}

list_my_generations

The user's finished BeautySpark look generations, newest first: title, date, thumbnail and whether it is already in My Looks. Pass a jobId to save_generation_to_my_looks to save one.

read-only

Argument	Type	Description
limit	integer	How many to return (default 20).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "How many to return (default 20)."
    }
  }
}

list_my_palettes

The palettes the user scanned in BeautySpark, with shade names and hex colors. Use them to advise with products the user owns; pass a paletteId as a product's userPaletteId in save_my_look.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

save_generation_to_my_looks

Save a finished BeautySpark generation (a jobId from list_my_generations) as a look in My Looks. Saving the same generation again returns the look already saved.

Argument	Type	Description
jobId*	string	A jobId from list_my_generations.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "jobId"
  ],
  "properties": {
    "jobId": {
      "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)$",
      "description": "A jobId from list_my_generations."
    }
  }
}

save_my_look

Save a new look to the user's BeautySpark My Looks. Photos can't be added from chat: if the user attached or mentions a photo, tell them before saving that only the text is saved and that they can add the photo in BeautySpark from the returned link. Repeating the same save within 10 minutes returns the first look instead of a copy.

Argument	Type	Description
notes	string	Free-text notes about the look.
steps	array	Ordered steps, first to last. Each step: instruction (required); title; area; positions = where on the eye, only when area is "eyes"; technique (free text); toolsNeeded = tool slugs from the allowed values only; intensity; estimatedTime in minutes (max 120); notes; productRefs = 0-based indexes into this look's products; shadeRefs = {productIndex, shadeIndex}, 0-based indexes into products and that product's shades. Leave photoAssetId and position unset.
title*	string	Short name for the look, e.g. "Soft bronze smoky eye".
products	array	Products used. Each: name (required); productType, e.g. "eyeshadow palette"; area; userPaletteId = the paletteId from list_my_palettes when it is a palette the user owns; shades = the pans used, each with name, hexColor (#RRGGBB) and position in the palette.
tagNames	array	Tag names. A name the user already has reuses that tag; a new name creates one.
occasions	array	Free-text occasions, e.g. ["office", "wedding guest"].
personName	string	Name of one of the user's persons in BeautySpark (exact name, any case). Leave it out unless the user names someone.
isFavourite	boolean	Mark the look as a favourite.
categorySlugs	array	Categories: preset slugs (everyday, work, date_night, evening, party, festival, wedding_guest, bridal, prom, holiday, vacation, photoshoot, editorial, no_makeup, smokey, glam, natural_glow, bold_color) or the names of the user's own categories.
inspirationUrl	string	An http(s) link to what inspired the look, kept as text. Never fetched.
intensityLevel	string	How strong the whole look is.
difficultyLevel	string	How hard the look is to do.
estimatedTotalTime	integer	Time for the whole look, in minutes.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "title"
  ],
  "properties": {
    "notes": {
      "type": "string",
      "maxLength": 4000,
      "description": "Free-text notes about the look."
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "instruction"
        ],
        "properties": {
          "area": {
            "enum": [
              "base",
              "brows",
              "eyes",
              "lashes",
              "cheeks",
              "lips",
              "other"
            ],
            "type": "string"
          },
          "notes": {
            "type": "string",
            "maxLength": 4000
          },
          "title": {
            "type": "string",
            "maxLength": 120
          },
          "position": {
            "enum": [
              "primer",
              "lid",
              "creaseTransition",
              "outerV",
              "innerCorner",
              "browBone",
              "upperLiner",
              "lowerLashLine",
              "waterline",
              "tightline",
              "halo",
              "cutCrease",
              "wing",
              "outerLowerLash"
            ],
            "type": "string"
          },
          "intensity": {
            "enum": [
              "very_subtle",
              "light",
              "medium",
              "bold",
              "dramatic"
            ],
            "type": "string"
          },
          "positions": {
            "type": "array",
            "items": {
              "enum": [
                "primer",
                "lid",
                "creaseTransition",
                "outerV",
                "innerCorner",
                "browBone",
                "upperLiner",
                "lowerLashLine",
                "waterline",
                "tightline",
                "halo",
                "cutCrease",
                "wing",
                "outerLowerLash"
              ],
              "type": "string"
            },
            "default": [],
            "maxItems": 14
          },
          "shadeRefs": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "productIndex",
                "shadeIndex"
              ],
              "properties": {
                "shadeIndex": {
                  "type": "integer",
                  "maximum": 9007199254740991,
                  "minimum": 0
                },
                "productIndex": {
                  "type": "integer",
                  "maximum": 9007199254740991,
                  "minimum": 0
                }
              }
            },
            "default": [],
            "maxItems": 24
          },
          "technique": {
            "type": "string",
            "maxLength": 200
          },
          "instruction": {
            "type": "string",
            "maxLength": 1000,
            "minLength": 1
          },
          "productRefs": {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 9007199254740991,
              "minimum": 0
            },
            "default": [],
            "maxItems": 20
          },
          "toolsNeeded": {
            "type": "array",
            "items": {
              "enum": [
                "brush_powder",
                "brush_foundation",
                "brush_blush",
                "brush_contour",
                "brush_highlight",
                "brush_eyeshadow_flat",
                "brush_eyeshadow_blending",
                "brush_eyeshadow_crease",
                "brush_eyeshadow_detail",
                "brush_eyeliner",
                "brush_lip",
                "brush_brow",
                "brush_fan",
                "brush_kabuki",
                "sponge_beauty_blender",
                "sponge_wedge",
                "sponge_silicone",
                "applicator_fingers",
                "applicator_cotton_pad",
                "applicator_cotton_swab",
                "applicator_lash_curler",
                "applicator_tweezers",
                "applicator_spoolie",
                "setting_spray",
                "primer",
                "tissue",
                "mirror",
                "brush_eyeshadow_smudge",
                "mascara_wand",
                "eyeliner_pencil",
                "eyeliner_liquid",
                "eyeshadow_stick",
                "lash_glue"
              ],
              "type": "string"
            },
            "default": [],
            "maxItems": 20
          },
          "photoAssetId": {
            "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)$"
          },
          "estimatedTime": {
            "type": "integer",
            "maximum": 120,
            "minimum": 0
          }
        }
      },
      "default": [],
      "maxItems": 30,
      "description": "Ordered steps, first to last. Each step: instruction (required); title; area; positions = where on the eye, only when area is \"eyes\"; technique (free text); toolsNeeded = tool slugs from the allowed values only; intensity; estimatedTime in minutes (max 120); notes; productRefs = 0-based indexes into this look's products; shadeRefs = {productIndex, shadeIndex}, 0-based indexes into products and that product's shades. Leave photoAssetId and position unset."
    },
    "title": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "description": "Short name for the look, e.g. \"Soft bronze smoky eye\"."
    },
    "products": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "area": {
            "type": "string",
            "maxLength": 60
          },
          "name": {
            "type": "string",
            "maxLength": 120,
            "minLength": 1
          },
          "shades": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "maxLength": 120
                },
                "hexColor": {
                  "type": "string",
                  "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"
                },
                "position": {
                  "type": "string",
                  "maxLength": 60
                }
              }
            },
            "default": [],
            "maxItems": 24
          },
          "productType": {
            "type": "string",
            "maxLength": 60
          },
          "userPaletteId": {
            "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)$"
          }
        }
      },
      "default": [],
      "maxItems": 20,
      "description": "Products used. Each: name (required); productType, e.g. \"eyeshadow palette\"; area; userPaletteId = the paletteId from list_my_palettes when it is a palette the user owns; shades = the pans used, each with name, hexColor (#RRGGBB) and position in the palette."
    },
    "tagNames": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40,
        "minLength": 1
      },
      "default": [],
      "maxItems": 20,
      "description": "Tag names. A name the user already has reuses that tag; a new name creates one."
    },
    "occasions": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60,
        "minLength": 1
      },
      "default": [],
      "maxItems": 10,
      "description": "Free-text occasions, e.g. [\"office\", \"wedding guest\"]."
    },
    "personName": {
      "type": "string",
      "maxLength": 50,
      "minLength": 1,
      "description": "Name of one of the user's persons in BeautySpark (exact name, any case). Leave it out unless the user names someone."
    },
    "isFavourite": {
      "type": "boolean",
      "default": false,
      "description": "Mark the look as a favourite."
    },
    "categorySlugs": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40,
        "minLength": 1
      },
      "default": [],
      "maxItems": 10,
      "description": "Categories: preset slugs (everyday, work, date_night, evening, party, festival, wedding_guest, bridal, prom, holiday, vacation, photoshoot, editorial, no_makeup, smokey, glam, natural_glow, bold_color) or the names of the user's own categories."
    },
    "inspirationUrl": {
      "type": "string",
      "maxLength": 2048,
      "description": "An http(s) link to what inspired the look, kept as text. Never fetched."
    },
    "intensityLevel": {
      "enum": [
        "very_subtle",
        "light",
        "medium",
        "bold",
        "dramatic"
      ],
      "type": "string",
      "description": "How strong the whole look is."
    },
    "difficultyLevel": {
      "enum": [
        "easy",
        "medium",
        "advanced"
      ],
      "type": "string",
      "description": "How hard the look is to do."
    },
    "estimatedTotalTime": {
      "type": "integer",
      "maximum": 1440,
      "minimum": 0,
      "description": "Time for the whole look, in minutes."
    }
  }
}

For research modes (deep research, company knowledge). In chat, use search_guides instead. Searches all public BeautySpark content: guide sections (id "<locale>/<slug>#<anchor>"), article looks (id "look:<id>") and colour-season palette pages (id "season:<season>"). Read any result with fetch.

read-only

Argument	Type	Description
query*	string
locale	string	The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 1000,
      "minLength": 1
    },
    "locale": {
      "type": "string",
      "maxLength": 35,
      "description": "The user's language as a language tag, e.g. \"de\" or \"pt-BR\". Set it from the user's language. Defaults to English."
    }
  }
}

search_guides

Search BeautySpark's makeup and colour-season guides for sections that answer a question, e.g. eyeliner for hooded eyes or how to find your undertone. Returns up to 5 sections with a short snippet and a link; read one in full with get_guide. Cite the returned url. When nothing matches, the result has a note saying no BeautySpark guide covers it.

read-only

Argument	Type	Description
type	string	Only articles of this type.
limit	integer	Results to return, 1 to 5. Defaults to 5.
query*	string	Keywords for the makeup or colour question, e.g. "eyeliner hooded eyes".
locale	string	The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English.
season	string	Color season, e.g. "True Winter" or "true_winter". One of the 12 seasons.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "query"
  ],
  "properties": {
    "type": {
      "enum": [
        "guide",
        "tutorial",
        "season",
        "tool",
        "product",
        "trend"
      ],
      "type": "string",
      "description": "Only articles of this type."
    },
    "limit": {
      "type": "integer",
      "maximum": 5,
      "minimum": 1,
      "description": "Results to return, 1 to 5. Defaults to 5."
    },
    "query": {
      "type": "string",
      "maxLength": 1000,
      "minLength": 1,
      "description": "Keywords for the makeup or colour question, e.g. \"eyeliner hooded eyes\"."
    },
    "locale": {
      "type": "string",
      "maxLength": 35,
      "description": "The user's language as a language tag, e.g. \"de\" or \"pt-BR\". Set it from the user's language. Defaults to English."
    },
    "season": {
      "type": "string",
      "maxLength": 40,
      "description": "Color season, e.g. \"True Winter\" or \"true_winter\". One of the 12 seasons."
    }
  }
}

search_my_looks

Search the user's saved looks in BeautySpark My Looks by words, tag, category, favourite or person. Returns look ids for get_my_look.

read-only

Argument	Type	Description
q	string	Text to find in look titles, notes, product, shade and palette names. Use tag for tags.
tag	string	Only looks with this tag name.
limit	integer	Looks per page (default 20).
cursor	string	nextCursor from the previous page.
person	string	Only looks for this person (exact name, any case).
category	string	Only looks in this category (preset slug or the user's own category name).
favourite	boolean	true for favourites only.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "q": {
      "type": "string",
      "maxLength": 200,
      "description": "Text to find in look titles, notes, product, shade and palette names. Use tag for tags."
    },
    "tag": {
      "type": "string",
      "maxLength": 40,
      "minLength": 1,
      "description": "Only looks with this tag name."
    },
    "limit": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Looks per page (default 20)."
    },
    "cursor": {
      "type": "string",
      "maxLength": 400,
      "description": "nextCursor from the previous page."
    },
    "person": {
      "type": "string",
      "maxLength": 50,
      "minLength": 1,
      "description": "Only looks for this person (exact name, any case)."
    },
    "category": {
      "type": "string",
      "maxLength": 40,
      "minLength": 1,
      "description": "Only looks in this category (preset slug or the user's own category name)."
    },
    "favourite": {
      "type": "boolean",
      "description": "true for favourites only."
    }
  }
}

try_look_from_photo

Prepare a try-on: BeautySpark recreates a makeup look on the user's selfie. Give one reference: articleLookId (from find_article_looks) or savedLookId (from search_my_looks). Photos (a reference photo or a different selfie) can only be uploaded in the try-on widget, never taken from chat attachments. The saved selfie is used unless the user uploads another in the widget. Returns the credit cost and balance without charging; nothing is generated until confirm_look_generation.

Argument	Type	Description
savedLookId	string	A saved look id from search_my_looks, to try one of the user's own looks on.
selfiePhoto	object	Set by the try-on widget in ChatGPT. Leave unset.
articleLookId	string	A look id from find_article_looks, to try that article look on.
referencePhoto	object	Set by the try-on widget in ChatGPT. Leave unset.
selfieUploadId	string	Set by the try-on widget after an upload. Leave unset.
referenceUploadId	string	Set by the try-on widget after an upload. Leave unset.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "savedLookId": {
      "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)$",
      "description": "A saved look id from search_my_looks, to try one of the user's own looks on."
    },
    "selfiePhoto": {
      "type": "object",
      "required": [
        "download_url",
        "file_id"
      ],
      "properties": {
        "file_id": {
          "type": "string"
        },
        "file_name": {
          "type": "string"
        },
        "mime_type": {
          "type": "string"
        },
        "download_url": {
          "type": "string"
        }
      },
      "description": "Set by the try-on widget in ChatGPT. Leave unset."
    },
    "articleLookId": {
      "type": "string",
      "maxLength": 400,
      "minLength": 1,
      "description": "A look id from find_article_looks, to try that article look on."
    },
    "referencePhoto": {
      "type": "object",
      "required": [
        "download_url",
        "file_id"
      ],
      "properties": {
        "file_id": {
          "type": "string"
        },
        "file_name": {
          "type": "string"
        },
        "mime_type": {
          "type": "string"
        },
        "download_url": {
          "type": "string"
        }
      },
      "description": "Set by the try-on widget in ChatGPT. Leave unset."
    },
    "selfieUploadId": {
      "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)$",
      "description": "Set by the try-on widget after an upload. Leave unset."
    },
    "referenceUploadId": {
      "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)$",
      "description": "Set by the try-on widget after an upload. Leave unset."
    }
  }
}

update_my_look

Change a saved look. Only the fields you send change; list fields (steps, products, tags, categories, occasions) replace the stored list whole. Look photos are kept. Steps can't be changed while any step has a photoUrl; the user edits those steps in the BeautySpark app. When the look's steps link products or shades, send productRefs and shadeRefs on every step you send ([] for a step with none): a step sent without them is refused unless products is sent too. To unlink every step, send products too.

destructive

Argument	Type	Description
id*	string	A saved look id from search_my_looks.
notes	any	Free-text notes about the look. Send null to clear it.
steps	array	Ordered steps, first to last. Each step: instruction (required); title; area; positions = where on the eye, only when area is "eyes"; technique (free text); toolsNeeded = tool slugs from the allowed values only; intensity; estimatedTime in minutes (max 120); notes; productRefs = 0-based indexes into this look's products; shadeRefs = {productIndex, shadeIndex}, 0-based indexes into products and that product's shades. Leave photoAssetId and position unset. Replaces the whole stored list, so send the complete list.
title	string	Short name for the look, e.g. "Soft bronze smoky eye".
products	array	Products used. Each: name (required); productType, e.g. "eyeshadow palette"; area; userPaletteId = the paletteId from list_my_palettes when it is a palette the user owns; shades = the pans used, each with name, hexColor (#RRGGBB) and position in the palette. Replaces the whole stored list, so send the complete list. Send steps too, so their productRefs stay correct.
tagNames	array	Tag names. A name the user already has reuses that tag; a new name creates one. Replaces the whole stored list, so send the complete list.
occasions	array	Free-text occasions, e.g. ["office", "wedding guest"]. Replaces the whole stored list, so send the complete list.
personName	any	Name of one of the user's persons in BeautySpark (exact name, any case). Leave it out unless the user names someone. Send null to clear it.
isFavourite	boolean	Mark the look as a favourite.
categorySlugs	array	Categories: preset slugs (everyday, work, date_night, evening, party, festival, wedding_guest, bridal, prom, holiday, vacation, photoshoot, editorial, no_makeup, smokey, glam, natural_glow, bold_color) or the names of the user's own categories. Replaces the whole stored list, so send the complete list.
inspirationUrl	any	An http(s) link to what inspired the look, kept as text. Never fetched. Send null to clear it.
intensityLevel	string	How strong the whole look is.
difficultyLevel	string	How hard the look is to do.
estimatedTotalTime	integer	Time for the whole look, in minutes.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "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)$",
      "description": "A saved look id from search_my_looks."
    },
    "notes": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 4000
        },
        {
          "type": "null"
        }
      ],
      "description": "Free-text notes about the look. Send null to clear it."
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "instruction"
        ],
        "properties": {
          "area": {
            "enum": [
              "base",
              "brows",
              "eyes",
              "lashes",
              "cheeks",
              "lips",
              "other"
            ],
            "type": "string"
          },
          "notes": {
            "type": "string",
            "maxLength": 4000
          },
          "title": {
            "type": "string",
            "maxLength": 120
          },
          "position": {
            "enum": [
              "primer",
              "lid",
              "creaseTransition",
              "outerV",
              "innerCorner",
              "browBone",
              "upperLiner",
              "lowerLashLine",
              "waterline",
              "tightline",
              "halo",
              "cutCrease",
              "wing",
              "outerLowerLash"
            ],
            "type": "string"
          },
          "intensity": {
            "enum": [
              "very_subtle",
              "light",
              "medium",
              "bold",
              "dramatic"
            ],
            "type": "string"
          },
          "positions": {
            "type": "array",
            "items": {
              "enum": [
                "primer",
                "lid",
                "creaseTransition",
                "outerV",
                "innerCorner",
                "browBone",
                "upperLiner",
                "lowerLashLine",
                "waterline",
                "tightline",
                "halo",
                "cutCrease",
                "wing",
                "outerLowerLash"
              ],
              "type": "string"
            },
            "default": [],
            "maxItems": 14
          },
          "shadeRefs": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "productIndex",
                "shadeIndex"
              ],
              "properties": {
                "shadeIndex": {
                  "type": "integer",
                  "maximum": 9007199254740991,
                  "minimum": 0
                },
                "productIndex": {
                  "type": "integer",
                  "maximum": 9007199254740991,
                  "minimum": 0
                }
              }
            },
            "maxItems": 24
          },
          "technique": {
            "type": "string",
            "maxLength": 200
          },
          "instruction": {
            "type": "string",
            "maxLength": 1000,
            "minLength": 1
          },
          "productRefs": {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 9007199254740991,
              "minimum": 0
            },
            "maxItems": 20
          },
          "toolsNeeded": {
            "type": "array",
            "items": {
              "enum": [
                "brush_powder",
                "brush_foundation",
                "brush_blush",
                "brush_contour",
                "brush_highlight",
                "brush_eyeshadow_flat",
                "brush_eyeshadow_blending",
                "brush_eyeshadow_crease",
                "brush_eyeshadow_detail",
                "brush_eyeliner",
                "brush_lip",
                "brush_brow",
                "brush_fan",
                "brush_kabuki",
                "sponge_beauty_blender",
                "sponge_wedge",
                "sponge_silicone",
                "applicator_fingers",
                "applicator_cotton_pad",
                "applicator_cotton_swab",
                "applicator_lash_curler",
                "applicator_tweezers",
                "applicator_spoolie",
                "setting_spray",
                "primer",
                "tissue",
                "mirror",
                "brush_eyeshadow_smudge",
                "mascara_wand",
                "eyeliner_pencil",
                "eyeliner_liquid",
                "eyeshadow_stick",
                "lash_glue"
              ],
              "type": "string"
            },
            "default": [],
            "maxItems": 20
          },
          "photoAssetId": {
            "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)$"
          },
          "estimatedTime": {
            "type": "integer",
            "maximum": 120,
            "minimum": 0
          }
        }
      },
      "maxItems": 30,
      "description": "Ordered steps, first to last. Each step: instruction (required); title; area; positions = where on the eye, only when area is \"eyes\"; technique (free text); toolsNeeded = tool slugs from the allowed values only; intensity; estimatedTime in minutes (max 120); notes; productRefs = 0-based indexes into this look's products; shadeRefs = {productIndex, shadeIndex}, 0-based indexes into products and that product's shades. Leave photoAssetId and position unset. Replaces the whole stored list, so send the complete list."
    },
    "title": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "description": "Short name for the look, e.g. \"Soft bronze smoky eye\"."
    },
    "products": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "area": {
            "type": "string",
            "maxLength": 60
          },
          "name": {
            "type": "string",
            "maxLength": 120,
            "minLength": 1
          },
          "shades": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "maxLength": 120
                },
                "hexColor": {
                  "type": "string",
                  "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"
                },
                "position": {
                  "type": "string",
                  "maxLength": 60
                }
              }
            },
            "default": [],
            "maxItems": 24
          },
          "productType": {
            "type": "string",
            "maxLength": 60
          },
          "userPaletteId": {
            "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)$"
          }
        }
      },
      "maxItems": 20,
      "description": "Products used. Each: name (required); productType, e.g. \"eyeshadow palette\"; area; userPaletteId = the paletteId from list_my_palettes when it is a palette the user owns; shades = the pans used, each with name, hexColor (#RRGGBB) and position in the palette. Replaces the whole stored list, so send the complete list. Send steps too, so their productRefs stay correct."
    },
    "tagNames": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40,
        "minLength": 1
      },
      "maxItems": 20,
      "description": "Tag names. A name the user already has reuses that tag; a new name creates one. Replaces the whole stored list, so send the complete list."
    },
    "occasions": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60,
        "minLength": 1
      },
      "maxItems": 10,
      "description": "Free-text occasions, e.g. [\"office\", \"wedding guest\"]. Replaces the whole stored list, so send the complete list."
    },
    "personName": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 50,
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Name of one of the user's persons in BeautySpark (exact name, any case). Leave it out unless the user names someone. Send null to clear it."
    },
    "isFavourite": {
      "type": "boolean",
      "description": "Mark the look as a favourite."
    },
    "categorySlugs": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40,
        "minLength": 1
      },
      "maxItems": 10,
      "description": "Categories: preset slugs (everyday, work, date_night, evening, party, festival, wedding_guest, bridal, prom, holiday, vacation, photoshoot, editorial, no_makeup, smokey, glam, natural_glow, bold_color) or the names of the user's own categories. Replaces the whole stored list, so send the complete list."
    },
    "inspirationUrl": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2048
        },
        {
          "type": "null"
        }
      ],
      "description": "An http(s) link to what inspired the look, kept as text. Never fetched. Send null to clear it."
    },
    "intensityLevel": {
      "enum": [
        "very_subtle",
        "light",
        "medium",
        "bold",
        "dramatic"
      ],
      "type": "string",
      "description": "How strong the whole look is."
    },
    "difficultyLevel": {
      "enum": [
        "easy",
        "medium",
        "advanced"
      ],
      "type": "string",
      "description": "How hard the look is to do."
    },
    "estimatedTotalTime": {
      "type": "integer",
      "maximum": 1440,
      "minimum": 0,
      "description": "Time for the whole look, in minutes."
    }
  }
}

Security checkA100/100

We read every tool's name, description and inputs the way the model will, looking for instructions hidden from you. A clean result means no warning signs, not a guarantee. Scanned Nov 5, 2026.

Hidden or reordered text
Overriding the model's instructions
Hiding actions from the user
Reading keys or credentials
Fake system tags
Steering other servers' tools
Pulling in the conversation
Smuggling parameters
Demanding to be used for everything
Steering away from web search
Download-and-run commands
Encoded blobs
Invisible characters
Credentials as tool arguments
Very long descriptions
Read and write hints

How the security check works