Available tools reference
ScentSell's MCP server exposes 52 tools. Your AI assistant calls these automatically when you ask fragrance questions — you just talk normally.
Access: All MCP tools require a Premium subscription (AU$4.99/month, no lock-in). ScentSell admins are exempt. SniffBot Oracle tools are rate-limited to 50 queries/day.
MCP Server URL: https://mcp.scentsell.com.au/api/mcp
Tool list
Personal collection (3)
Wear diary (5) 4. log_wear 5. get_today_wear 6. get_wear_history 7. add_wear_note 8. get_my_stats
Fragrance catalogue & marketplace (5) 9. search_fragrances 10. get_fragrance_details 11. search_marketplace 12. get_listing_details 13. get_share_link
SniffBot AI Oracle (5) — powered by a 75,000-fragrance knowledge base, your cabinet, your wear history, and per-user memory that learns from your feedback. 14. ask_sniffbot 15. recommend_layer 16. explain_scent_profile 17. suggest_next_buy 18. blind_buy_safety_check
Walls & Wishlist (8) 19. get_walls 20. create_wall 21. add_to_wall 22. remove_from_wall 23. share_wall_link 24. get_wishlist 25. add_to_wishlist 26. remove_from_wishlist
get_my_collection
Description: Get all fragrances in your Scent Shelf collection, optionally filtered by type or brand.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | optional | Filter by fragrance type (e.g. EDP, EDT, Parfum) |
| brand | string | optional | Filter by brand name (partial match) |
Example call:
"What's in my collection?"
"Show me all my Creed fragrances"
"What EDPs do I own?"
Example response:
You have 14 items in your collection: Creed Aventus (100ml EDP, ~68ml remaining), Maison Francis Kurkdjian Baccarat Rouge 540 (70ml EDP, ~42ml remaining)...
add_to_collection
Description: Add a new fragrance to your Scent Shelf collection. Will attempt to match against the fragrance database.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | required | Name of the fragrance |
| brand | string | required | Brand or house name |
| bottle_size_ml | number | optional | Bottle size in millilitres |
| fill_pct | number | optional | How full the bottle is (0–100%) |
| condition | string | optional | Bottle condition (Mint, Good, Fair) |
| notes | string | optional | Personal notes about this fragrance |
Example call:
"Add Dior Sauvage 100ml EDP to my collection, about 80% full"
Example response:
Added Dior Sauvage EDP (100ml, 80% full — ~80ml remaining) to your collection.
remove_from_collection
Description: Remove a fragrance from your collection (soft delete — can be recovered from settings).
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| collection_item_id | string | required | The ID of the collection item to remove |
Example call:
"Remove Sauvage from my collection"
If the name is ambiguous (you have multiple items with similar names), the AI will ask you to confirm which one before removing.
log_wear
Description: Log that you wore a fragrance today. You can identify the fragrance by name or collection item ID. Remaining ml is automatically decremented.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| collection_item_id | string | one of | Specific item ID (use when name is ambiguous) |
| fragrance_name | string | one of | Fragrance name (fuzzy-matched against your collection) |
| notes | string | optional | Notes about this wear (mood, occasion, weather, etc.) |
| worn_at | string | optional | ISO datetime for past wears (defaults to now) |
Example call:
"I'm wearing Aventus today for work, 4 sprays, hot sunny day"
"Log a wear for yesterday — Tom Ford Oud Wood, casual, 3 sprays"
Example response:
Logged! That's wear #14 of Creed Aventus. Bottle now has approximately 65ml remaining.
get_today_wear
Description: Get all fragrances you've logged wearing today.
Arguments: None
Example call:
"What have I worn today?"
"Show me today's wears"
Example response:
Today you've worn: Creed Aventus (4 sprays, 9am, work occasion)
get_wear_history
Description: Get your fragrance wear history, optionally filtered by fragrance name and date range.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| fragrance_name | string | optional | Filter by fragrance name (partial match) |
| days | number | optional | Number of days to look back (default: 30, max: 365) |
| limit | number | optional | Maximum entries to return (default: 50, max: 200) |
Example call:
"What have I worn in the last 7 days?"
"Show me my Aventus wear history"
"What did I wear last week?"
Example response:
Last 7 days (8 wears): Creed Aventus × 3, Baccarat Rouge 540 × 2, Tom Ford Oud Wood × 2, YSL Y EDP × 1
add_wear_note
Description: Append a note to an existing wear log entry.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| wear_log_id | string | required | ID of the wear log entry to update |
| note | string | required | Note text to append |
Example call:
"Add a note to today's Aventus wear: incredible projection in the heat, got 3 compliments"
Example response:
Note added to today's Creed Aventus wear log.
get_my_stats
Description: Get statistics about your fragrance collection and wear history including top worn fragrances.
Arguments: None
Example call:
"What's my most worn fragrance this year?"
"Give me my fragrance stats"
Example response:
Your stats: 48 total wears this month, 127 items in collection. Most worn: Creed Aventus (22 wears all time), Dior Sauvage (18 wears). Most worn this month: Baccarat Rouge 540 (6 wears).
search_fragrances
Description: Search the ScentSell fragrance catalogue (75,000+ fragrances). Returns name, brand, concentration, year, average price AUD, AU availability, and rating. Use this to find a fragrance before looking it up in detail or searching the marketplace.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | optional | Free-text match against fragrance name or brand |
| brand | string | optional | Filter by brand/house name (partial match) |
| limit | number | optional | Max results (default 20, max 50) |
Example call:
"Search ScentSell for Aventus"
"What's in Maison Crivelli's range?"
Example response:
Found 3 fragrance(s): • Aventus — Creed Eau de Parfum (2010) · 4.34★ · ~AU$580 • absolu-aventus — Creed (2023) · 4.19★ • Aventus For Her — Creed Eau de Parfum
get_fragrance_details
Description: Get full details for one fragrance — top/heart/base notes, main accords, perfumer, family, longevity, sillage, rating, pricing, AU availability, description.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| fragrance_id | string | optional | fragrance_master UUID (preferred — exact match) |
| name | string | optional | Used for fuzzy match if no id |
| brand | string | optional | Used with name for fuzzy match |
Example call:
"Tell me about Maison Crivelli Hibiscus Mahajad"
"What notes are in Aventus?"
Example response:
Hibiscus Mahajad by Maison Crivelli Concentration: extrait Family: Floral Spicy Top notes: Hibiscus, Cardamom, Pink Pepper Heart notes: Rose, Saffron, Jasmine Base notes: Oud, Sandalwood, Amber Average price: AU$320
search_marketplace
Description: Search active ScentSell marketplace listings (fragrances for sale by members). Returns name, brand, size, fill %, condition, price AUD, offer support, rarity, shipping origin. Use this when the user asks if a fragrance is available to buy.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | optional | Free-text match against fragrance name or brand |
| brand | string | optional | Filter by brand (partial match) |
| max_price_aud | number | optional | Max asking price in AUD |
| min_size_ml | number | optional | Minimum bottle/decant size in ml |
| limit | number | optional | Max results (default 20, max 50) |
Example call:
"Find me a Maison Crivelli on ScentSell"
"Any Creed Aventus under $400?"
Example response:
Found 2 active listing(s): • Hibiscus Mahajad — Maison Crivelli extrait 50ml @ 60% · lightly_used · AU$197.37 · ships from NSW • Hibiscus Mahajad — Maison Crivelli extrait 50ml @ 95% · new_open · AU$304.76 · ships from QLD
get_listing_details
Description: Get full details for a specific marketplace listing — condition notes, packaging, price breakdown, offer terms, shipping origin, batch code, description, acquisition history.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| listing_id | string | required | The listing id from search_marketplace |
Example call:
"Tell me more about that NSW Hibiscus Mahajad"
get_share_link
Description: Generate a shareable URL the user can open to download a social-media card (1080×1920 vertical for Reels/Stories, 1080×1350 portrait for Feed, 1080×1080 square) of their collection item, wear log, stats, or full collection.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| kind | enum | required | collection_item, wear_log, stats, or collection_overview |
| id | string | conditional | Required for collection_item and wear_log — pass the id from get_my_collection or get_wear_history |
Example call:
"Give me a share card for my Tom Ford ébène fumé"
"Make a share link for my stats"
Example response:
Shareable card for ebene-fume by Tom Ford: https://www.scentsell.com.au/shelf/abc-123?share=open Open in a logged-in browser to download the card.
SniffBot AI Oracle tools
These 5 tools are powered by SniffBot — ScentSell's fragrance expert AI. SniffBot is grounded in the 75,000+ fragrance catalogue, your personal collection, your wear history, and curated knowledge about layering, blind-buy safety, and fragrance families. It learns your taste over time from thumbs up/down feedback.
ask_sniffbot
Description: Freeform fragrance Q&A. Ask anything — reformulations, dupes, performance, authentication tips, history, pricing, Australian availability. SniffBot searches the catalogue, checks your collection, and grounds every answer in data.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| question | string | required | Your fragrance question |
Example calls:
"Is Dior Sauvage still worth buying in 2026?"
"What's the difference between Aventus and Club de Nuit Intense?"
"Has Bleu de Chanel been reformulated?"
recommend_layer
Description: Get 3–5 fragrance layering pairings for a given scent, with reasoning (accord harmony, season, occasion). Prefers items already in your collection when relevant.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| fragrance | string | required | Fragrance name or ID to find layering partners for |
Example calls:
"What layers well with Oud Wood on a summer day?"
"Give me layering ideas for Baccarat Rouge 540"
Example response:
Three pairings for Tom Ford Oud Wood (EDP, 2007):
- Iris + Oud — powdery iris cuts oud's intensity. Try Dior Homme Intense underneath.
- Rose + Oud — classic Middle Eastern pairing. By Kilian Rose Oud if you have it.
- Vetiver + Oud — earthy green base extends the woody drydown. Guerlain Vetiver works.
explain_scent_profile
Description: Get a structured expert breakdown of one fragrance — olfactive family, top/heart/base notes, dominant accords, perfumer, release year, projection/longevity, ideal Australian occasion + season, and 3 similar fragrances.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| fragrance | string | required | Fragrance name or ID |
Example calls:
"Break down Maison Crivelli Hibiscus Mahajad for me"
"What's the full scent profile of Aventus?"
suggest_next_buy
Description: Analyses your collection and wear history to recommend what to buy next. Identifies gaps in your cabinet (e.g., no fresh citrus, no winter warmer) and suggests specific fragrances with pricing + marketplace availability.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| budget_aud | number | optional | Maximum budget in AUD |
| occasion | string | optional | Target occasion or season (e.g., "summer daily", "date night", "office") |
Example calls:
"What should I buy next under $200 for date night?"
"I need a summer fragrance — what's missing from my collection?"
"Suggest something under $150 that I don't already own"
Example response:
Your collection is strong on woody-oud (Oud Wood, Aventus) but has no fresh aquatic for Brisbane summers. Try:
- Acqua di Gio Profondo (Armani, EDP, 2020) — ~AU$130 for 75ml. Marine-aquatic with a mineral drydown. Currently 2 listings on ScentSell from AU$89.
- Bleu de Chanel (Chanel, EDP, 2014) — ~AU$165. Versatile fresh-woody, works office to dinner.
blind_buy_safety_check
Description: Pass a ScentSell marketplace listing and SniffBot assesses blind-buy safety using a 5-point rubric: authenticity signals, condition vs price, AU market norms, reformulation/batch-era risk, and buyer-risk calibration. Returns a LOW/MEDIUM/HIGH risk verdict.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
| listing_id | string | required | The listing ID from search_marketplace |
Example calls:
"Is this Creed Aventus listing a safe blind buy?" (after searching marketplace)
"Check the safety of listing abc-123"
Example response:
Blind-buy safety: HIGH RISK
- Creed Aventus is a Tier-1 counterfeit target in Australia
- New seller (no rating history) — red flag (-1.0)
- No batch-code photo provided — red flag (-1.5)
- Price 35% below market — red flag (-2.0)
- Score: 2.5/10 — AVOID
Recommendation: Request batch-code photos before purchasing. Consider buying from an established seller with 4.5+ rating instead.
Walls & Wishlist tools
get_walls
List your walls and their item counts.
Args: none
Example prompts:
- "What are my walls?"
- "List my top 10s"
Returns: { walls: Array<{ id, name, category, slug, item_count }> }
create_wall
Create a new Top 10 wall. Category is optional — defaults to "custom".
Args:
name(string, required)category(string, optional) — one of:all_time,right_now,summer,autumn,winter,spring,date_night,everyday,freshies,clean,formal,workout,signature,custom
Example prompts:
- "Create a Date Night top 10"
- "Make me a summer wall"
Returns: { wall: Wall, permalink: string }
add_to_wall
Add a fragrance from your cabinet to a named wall. Wall names and fragrance names are fuzzy-matched.
Args:
wall_name_or_slug(string, required)fragrance_query(string, required) — e.g. "Aventus", "Xerjoff Naxos"position(integer 1–10, optional)
Example prompts:
- "Add Aventus to my summer top 10"
- "Put Baccarat Rouge 540 in Date Night"
Returns: { wall, item, message }
remove_from_wall
Remove a fragrance from a named wall.
Args:
wall_name_or_slug(string, required)fragrance_query(string, required)
Example prompts:
- "Take Aventus off my summer top 10"
Returns: { removed: boolean, message }
share_wall_link
Get the public permalink URL for a named wall.
Args:
wall_name_or_slug(string, required)
Example prompts:
- "Share my all-time top 10"
- "Get the link for my date night wall"
Returns: { permalink: string }
get_wishlist
List your wishlist with cabinet-overlap flags.
Args: none
Example prompts:
- "What's on my wishlist?"
Returns: { items: Array<{ id, brand, name, concentration, in_cabinet }> }
add_to_wishlist
Add a catalogue fragrance to your wishlist. Matches by brand + name fuzzy search.
Args:
fragrance_query(string, required)
Example prompts:
- "Wishlist Tubéreuse Criminelle"
- "Add Maison Crivelli to my wishlist"
Returns: { added: boolean, item, message }
remove_from_wishlist
Remove a fragrance from your wishlist.
Args:
fragrance_query(string, required)
Example prompts:
- "Take Mandarino off my wishlist"
Returns: { removed: boolean, message }
Next steps:
Phase 8 — Full Parity (2026-04-18)
Phase 8 added 26 new tools (13 reads + 13 mutations), bringing the total to 52. These tools give your AI assistant full parity with the ScentSell web app — anything you can do in a browser you can now do by talking to Claude, Cursor, or any MCP-compatible client.
Intelligence
get_intelligence_nudges
Fetch personalised nudges from the ScentSell intelligence engine (low-stock alerts, restock suggestions, wear-streak notices).
Args: { limit?: number }
Example prompt: "What nudges does ScentSell have for me?"
Returns: { nudges: Array<{ type, message, fragrance_id?, urgency }> }
get_intelligence_settings
Retrieve the user's current intelligence / notification preferences (which nudge types are enabled, frequency caps, etc.).
Args: {}
Example prompt: "What intelligence notifications am I subscribed to?"
Returns: { settings: IntelligenceSettings }
update_intelligence_settings
Update intelligence preferences — enable or disable nudge categories, adjust frequency caps.
Args: { settings: Partial<IntelligenceSettings> }
Example prompt: "Turn off low-stock alerts for me"
Returns: { updated: boolean, settings: IntelligenceSettings }
Weather
get_current_weather
Get the current weather and season context for the user's saved location — used by SniffBot to tailor fragrance recommendations.
Args: { location?: string }
Example prompt: "What's the weather context for my fragrance recommendations today?"
Returns: { location, temperature_c, condition, season, humidity_pct }
Share card data
get_scent_of_day_data
Get the structured data behind the user's Scent of the Day share card — today's wear, notes, bottle art, mood tags.
Args: {}
Example prompt: "Get my scent of the day card data"
Returns: { wear_log, fragrance, card_url, share_text }
get_weekly_recap_data
Get the structured data for the user's weekly recap share card — top fragrances this week, total wears, streak.
Args: { week_offset?: number }
Example prompt: "What does my weekly recap card look like?"
Returns: { week_label, total_wears, top_fragrances, streak_days, card_url }
get_monthly_recap_data
Get the structured data for the user's monthly recap share card — most worn, new additions, ml consumed.
Args: { month?: string }
Example prompt: "Show me my monthly recap for March"
Returns: { month_label, total_wears, most_worn, new_additions, ml_consumed, card_url }
Cabinet advanced
search_my_collection
Full-text search within the user's own collection — finds items by fragrance name, brand, personal notes, or tags.
Args: { query: string, limit?: number }
Example prompt: "Find anything in my collection with bergamot notes"
Returns: { items: Array<CollectionItem> }
get_collection_stats
Get detailed analytics for the user's collection — brand distribution, concentration breakdown, average fill, total ml value, wear frequency by fragrance.
Args: {}
Example prompt: "Give me detailed stats on my collection"
Returns: { brand_counts, concentration_counts, avg_fill_pct, total_ml, total_items, wear_frequency }
Wall management
rename_wall
Rename an existing wall.
Args: { wall_id: string, new_name: string }
Example prompt: "Rename my 'Summer' wall to 'Hot Weather Picks'"
Returns: { updated: boolean, wall }
delete_wall
Permanently delete a wall and all its items.
Args: { wall_id: string }
Example prompt: "Delete my outdated winter wall"
Returns: { deleted: boolean }
reorder_wall
Reorder items within a wall by providing a new ordered list of item IDs.
Args: { wall_id: string, ordered_item_ids: string[] }
Example prompt: "Move Aventus to the top of my all-time wall"
Returns: { updated: boolean, wall }
Wishlist priority
update_wishlist_priority
Set or change the priority rank of a wishlist item (1 = most wanted).
Args: { wishlist_item_id: string, priority: number }
Example prompt: "Make Tubéreuse Criminelle my #1 wishlist item"
Returns: { updated: boolean, item }
Wear log management
update_wear_log
Edit an existing wear log entry — change notes, occasion, sprays count, or worn_at datetime.
Args: { wear_log_id: string, notes?: string, occasion?: string, sprays_count?: number, worn_at?: string }
Example prompt: "Update yesterday's Aventus wear — it was a date night, not work"
Returns: { updated: boolean, wear_log }
delete_wear_log
Delete a wear log entry (restores any ml that was decremented).
Args: { wear_log_id: string }
Example prompt: "Delete that accidental wear log I just created"
Returns: { deleted: boolean, ml_restored?: number }
Listing creation
create_listing_draft
Create a draft marketplace listing for a fragrance in the user's collection. Returns the listing ID and a link to the edit page to finalise price, photos, and description before submitting for review.
Args: { collection_item_id: string, asking_price_aud: number, accepts_offers?: boolean, description?: string }
Example prompt: "List my Creed Aventus for $350, accepting offers"
Returns: { listing_id, edit_url, status: 'draft' }
Offers
make_offer
Submit a purchase offer on a marketplace listing.
Args: { listing_id: string, offer_amount_aud: number, message?: string }
Example prompt: "Offer $280 on the Aventus listing"
Returns: { offer_id, status, expires_at }
respond_to_offer
Accept, decline, or counter an offer received on one of the user's listings.
Args: { offer_id: string, action: 'accept' | 'decline' | 'counter', counter_amount_aud?: number, message?: string }
Example prompt: "Accept the offer on my Oud Wood listing"
Returns: { offer_id, status, checkout_url? }
get_my_offers
List all active offers — both offers the user has made and offers received on their listings.
Args: { direction?: 'sent' | 'received' | 'all', status?: string }
Example prompt: "Show me all my open offers"
Returns: { offers: Array<{ id, listing, amount, status, direction, expires_at }> }
Brand alerts
set_brand_alert
Subscribe to restock / new listing alerts for a fragrance brand or house.
Args: { brand: string, alert_type?: 'new_listing' | 'price_drop' | 'both' }
Example prompt: "Alert me when Maison Crivelli listings appear"
Returns: { alert_id, brand, alert_type, created: boolean }
get_brand_alerts
List all active brand alerts for the user.
Args: {}
Example prompt: "What brand alerts do I have set up?"
Returns: { alerts: Array<{ id, brand, alert_type, created_at }> }
remove_brand_alert
Remove a brand alert subscription.
Args: { alert_id: string }
Example prompt: "Turn off alerts for Dior"
Returns: { removed: boolean }
Profile
get_my_profile
Fetch the user's public profile — display name, bio, ratings, seller stats, collection count, verified status.
Args: {}
Example prompt: "What does my ScentSell profile look like?"
Returns: { profile: Profile }
update_my_profile
Update editable profile fields — display name, bio, location, Instagram handle.
Args: { display_name?: string, bio?: string, location?: string, instagram_handle?: string }
Example prompt: "Update my bio to 'Oud collector based in Melbourne'"
Returns: { updated: boolean, profile: Profile }
Market data
get_recently_sold
Fetch recently completed sales on the ScentSell marketplace — useful for pricing context when listing or buying.
Args: { query?: string, brand?: string, limit?: number }
Example prompt: "What has Creed Aventus sold for recently on ScentSell?"
Returns: { sales: Array<{ fragrance, size_ml, condition, sold_price_aud, sold_at }> }
get_curated_collections
Fetch admin-curated spotlight collections — themed packs like "Summer Freshies" or "Under $100 Gems".
Args: { limit?: number }
Example prompt: "Show me ScentSell's curated collections"
Returns: { collections: Array<{ id, title, description, item_count, permalink }> }