Color-season palettes, product picks and makeup looks from BeautySpark's guides
Scored across 22 tools
Most tools target a distinct resource-and-action pair (guides vs. article looks vs. my looks vs. generations vs. palettes vs. try-on steps). The main soft spot is the parallel 'search/fetch' pair restricted to research modes alongside 'search_guides/get_guide' for chat, which an agent could plausibly mix up. Boundaries like save_my_look vs. save_generation_to_my_looks and get_color_season vs. list_my_palettes are clarified well enough by the descriptions.
Nearly all tools follow a verb_noun pattern (get_guide, search_my_looks, save_my_look, delete_my_look, try_look_from_photo). The two bare-verb names 'search' and 'fetch' are the notable deviations and are also the most generic labels on the server. Overall the set reads predictably and consistently across the 22 tools.
At 22 tools the surface is on the heavy side for the domain, and the mode-specific search/fetch duplicates add surface area that is unlikely to be used in ordinary chat interactions. Each tool maps to a real operation, but the set could plausibly be trimmed or consolidated.
The surface covers the core lifecycle well: discovering/reading guides and article looks, season palettes, product picks, full CRUD on My Looks, listing generations and saving them, and the complete try-on flow (prepare, confirm, status, upload). Minor gaps remain—no deletion or management of palettes, no product detail/search beyond season checks, and no profile update—but agents can work around these.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| shade | No | Shade name, e.g. "Flambé". | |
| locale | No | 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 | No | Color season, e.g. "True Winter" or "true_winter". One of the 12 seasons. | |
| product | Yes | Brand and product name, e.g. "ILIA Overglaze". |
| Name | Required | Description |
|---|---|---|
| match | Yes | |
| seasonPalette | No |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| quoteId | Yes | The quoteId from try_look_from_photo. |
| Name | Required | Description |
|---|---|---|
| jobId | Yes | |
| alreadyStarted | Yes |
Used by the try-on widget to upload a photo the user picked. Returns an upload URL valid for 15 minutes.
| Name | Required | Description | Default |
|---|---|---|---|
| contentType | Yes |
| Name | Required | Description |
|---|---|---|
| headers | Yes | |
| uploadId | Yes | |
| uploadUrl | Yes |
Delete a saved look from the user's BeautySpark My Looks. The look is removed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | A saved look id from search_my_looks. |
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 ("/#"), an article look ("look:") or a colour-season palette page ("season:").
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | An id returned by search. | |
| locale | No | The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| text | Yes | |
| title | Yes | |
| metadata | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Article type. | |
| limit | No | ||
| query | No | Words to match against the look title, tags and image description, e.g. "smoky", "graphic liner". | |
| locale | No | 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 | No | Color season, e.g. "True Winter" or "true_winter". One of the 12 seasons. |
| Name | Required | Description |
|---|---|---|
| looks | Yes |
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//").
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | A look id from find_article_looks, e.g. "/images/blog/<article-slug>/<look-name>". | |
| locale | No | The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| steps | Yes | |
| title | Yes | |
| shades | Yes | |
| webUrl | Yes | |
| thumbnailUrl | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | 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 | Yes | Color season, e.g. "True Winter" or "true_winter". One of the 12 seasons. |
| Name | Required | Description |
|---|---|---|
| lang | Yes | |
| advice | Yes | |
| season | Yes | |
| guideUrl | Yes | |
| swatches | Yes | |
| displayName | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | A section id returned by search_guides, e.g. "en/how-to-find-your-undertone#intro". |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| lang | Yes | |
| text | Yes | |
| title | Yes | |
| metadata | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | The jobId from confirm_look_generation. | |
| waitSeconds | No | Seconds to wait for completion before answering, 0 to 25. Use 25. |
| Name | Required | Description |
|---|---|---|
| step | Yes | |
| jobId | Yes | |
| steps | No | |
| status | Yes | |
| afterUrl | No | |
| progress | Yes | |
| stepsNote | No | |
| nextPollMs | Yes |
Get one saved look in full: steps, products and shades, tags, categories, notes, photos and a link to open it in BeautySpark.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | A saved look id from search_my_looks. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| tags | Yes | |
| notes | Yes | |
| steps | Yes | |
| title | Yes | |
| photos | Yes | |
| webUrl | Yes | |
| category | Yes | |
| personId | Yes | |
| products | Yes | |
| createdAt | Yes | |
| occasions | Yes | |
| updatedAt | Yes | |
| categories | Yes | |
| isFavourite | Yes | |
| sourceJobId | Yes | |
| inspirationUrl | Yes | |
| intensityLevel | Yes | |
| difficultyLevel | Yes | |
| estimatedTotalTime | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| note | No | |
| season | Yes | |
| eyeShape | Yes | |
| language | Yes | |
| faceShape | Yes | |
| undertone | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | 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 | Yes | Color season, e.g. "True Winter" or "true_winter". One of the 12 seasons. | |
| category | No | Only return picks of this category. |
| Name | Required | Description |
|---|---|---|
| picks | Yes | |
| season | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many to return (default 20). |
| Name | Required | Description |
|---|---|---|
| generations | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| palettes | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | A jobId from list_my_generations. |
| Name | Required | Description |
|---|---|---|
| look | Yes | |
| created | Yes | |
| summary | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | Free-text notes about the look. | |
| steps | No | 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 | Yes | Short name for the look, e.g. "Soft bronze smoky eye". | |
| products | No | 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 | No | Tag names. A name the user already has reuses that tag; a new name creates one. | |
| occasions | No | Free-text occasions, e.g. ["office", "wedding guest"]. | |
| personName | No | Name of one of the user's persons in BeautySpark (exact name, any case). Leave it out unless the user names someone. | |
| isFavourite | No | Mark the look as a favourite. | |
| categorySlugs | No | 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 | No | An http(s) link to what inspired the look, kept as text. Never fetched. | |
| intensityLevel | No | How strong the whole look is. | |
| difficultyLevel | No | How hard the look is to do. | |
| estimatedTotalTime | No | Time for the whole look, in minutes. |
| Name | Required | Description |
|---|---|---|
| look | Yes | |
| created | Yes | |
| summary | Yes |
For research modes (deep research, company knowledge). In chat, use search_guides instead. Searches all public BeautySpark content: guide sections (id "/#"), article looks (id "look:") and colour-season palette pages (id "season:"). Read any result with fetch.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| locale | No | The user's language as a language tag, e.g. "de" or "pt-BR". Set it from the user's language. Defaults to English. |
| Name | Required | Description |
|---|---|---|
| results | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Only articles of this type. | |
| limit | No | Results to return, 1 to 5. Defaults to 5. | |
| query | Yes | Keywords for the makeup or colour question, e.g. "eyeliner hooded eyes". | |
| locale | No | 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 | No | Color season, e.g. "True Winter" or "true_winter". One of the 12 seasons. |
| Name | Required | Description |
|---|---|---|
| note | No | |
| results | Yes |
Search the user's saved looks in BeautySpark My Looks by words, tag, category, favourite or person. Returns look ids for get_my_look.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Text to find in look titles, notes, product, shade and palette names. Use tag for tags. | |
| tag | No | Only looks with this tag name. | |
| limit | No | Looks per page (default 20). | |
| cursor | No | nextCursor from the previous page. | |
| person | No | Only looks for this person (exact name, any case). | |
| category | No | Only looks in this category (preset slug or the user's own category name). | |
| favourite | No | true for favourites only. |
| Name | Required | Description |
|---|---|---|
| looks | Yes | |
| total | Yes | |
| nextCursor | Yes |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| savedLookId | No | A saved look id from search_my_looks, to try one of the user's own looks on. | |
| selfiePhoto | No | Set by the try-on widget in ChatGPT. Leave unset. | |
| articleLookId | No | A look id from find_article_looks, to try that article look on. | |
| referencePhoto | No | Set by the try-on widget in ChatGPT. Leave unset. | |
| selfieUploadId | No | Set by the try-on widget after an upload. Leave unset. | |
| referenceUploadId | No | Set by the try-on widget after an upload. Leave unset. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | A saved look id from search_my_looks. | |
| notes | No | Free-text notes about the look. Send null to clear it. | |
| steps | No | 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 | No | Short name for the look, e.g. "Soft bronze smoky eye". | |
| products | No | 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 | No | 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 | No | Free-text occasions, e.g. ["office", "wedding guest"]. Replaces the whole stored list, so send the complete list. | |
| personName | No | 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 | No | Mark the look as a favourite. | |
| categorySlugs | No | 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 | No | An http(s) link to what inspired the look, kept as text. Never fetched. Send null to clear it. | |
| intensityLevel | No | How strong the whole look is. | |
| difficultyLevel | No | How hard the look is to do. | |
| estimatedTotalTime | No | Time for the whole look, in minutes. |
| Name | Required | Description |
|---|---|---|
| look | Yes | |
| created | Yes | |
| summary | Yes |
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
check_product_for_seasonconfirm_look_generationcreate_upload_urldelete_my_lookfetchfind_article_looksget_article_lookget_color_seasonget_guideget_look_statusget_my_lookget_my_profileget_product_pickslist_my_generationslist_my_palettessave_generation_to_my_lookssave_my_looksearchsearch_guidessearch_my_lookstry_look_from_photoupdate_my_look
Add one secure layer between your agents and this server.