ScentVerdict

Find Similar Fragrances

find_similar_fragrances

Read-onlyIdempotent

Find fragrances similar to one the user already knows, optionally steered in a direction such as cheaper, fresher, longer lasting or less sweet. Use this whenever the user names a fragrance and wants something like it: a cheaper alternative, a budget version, something that smells similar, or a gift for someone whose current fragrance they know ('he wears X, what else would suit him'). Each match carries a similarity score computed by ScentVerdict for that specific pair. The cheaper direction lists pairings ScentVerdict has curated first, then similar fragrances priced below the anchor where we hold its price. Each match carries its bottle price for the user's country, in the shop's own currency. Use recommend_fragrances instead when the user names no fragrance to anchor on.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum results. Default 5, maximum 10.
`country`	No	The user's country as an ISO 3166-1 alpha-2 code, for example US, DE or GB. Prices are for this country, in the shop's own currency. Pass it whenever you know where the user is. When omitted, the client's location hint is used if it sent one, otherwise GB.
`direction`	No	How to steer results away from the anchor. Defaults to the closest overall match.	Similar
`anchorSlug`	Yes	Slug of the fragrance to anchor on. Use search_fragrances first if you do not have one.

Output Schema

TableJSON Schema

Name	Required	Description
`market`	No	The country the prices in this result are for, its currency, and how it was chosen.
`reason`	Yes	Why the result set is empty. Null when results were found.
`results`	Yes	Ranked matches, closest first. May be empty.
`notFound`	No	Set when the anchor fragrance is not in the catalogue.
`direction`	Yes	How results were steered away from the anchor.
`anchorSlug`	Yes	The fragrance the results were derived from.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedOct 2, 2026

addedInput schema / properties / country

Added value: +{
+  "default": null,
+  "description": "The user's country as an ISO 3166-1 alpha-2 code, for example US, DE or GB. Prices are for this country, in the shop's own currency. Pass it whenever you know where the user is. When omitted, the client's location hint is used if it sent one, otherwise GB.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / market

Added value: +{
+  "default": null,
+  "description": "The country the prices in this result are for, its currency, and how it was chosen.",
+  "properties": {
+    "country": {
+      "description": "ISO 3166-1 alpha-2 country the prices are for, for example GB, US or DE.",
+      "type": "string"
+    },
+    "countryName": {
+      "description": "The country's name in English.",
+      "type": "string"
+    },
+    "currency": {
+      "description": "ISO 4217 code of that country's currency. Budgets are read in this currency.",
+      "type": "string"
+    },
+    "source": {
+      "description": "How the country was chosen: 'argument' (the country you passed), 'clientHint' (the client's location hint), or 'default' (GB, used when neither was given - ask the user for their country if it matters).",
+      "type": "string"
+    }
+  },
+  "required": [
+    "country",
+    "countryName",
+    "currency",
+    "source"
+  ],
+  "type": [
+    "object",
+    "null"
+  ]
+}

addedOutput schema / properties / results / items / properties / fragrance / properties / price

Added value: +{
+  "description": "Cheapest full-size bottle for the user's country, in the shop's own currency. Excludes samples and decants. Null when we hold no bottle price a shop will sell to that country.",
+  "properties": {
+    "amount": {
+      "description": "The bottle price, in Currency. This is the shop's own price, never a conversion.",
+      "type": "number"
+    },
+    "currency": {
+      "description": "ISO 4217 currency code of Amount, for example GBP, USD or EUR. The shop's own currency.",
+      "type": "string"
+    },
+    "estimate": {
+      "description": "Rough value of Amount in the user's currency, at a published reference rate. Present only when Currency differs from the user's currency and a recent rate exists. For orientation only: never use it to rank, compare or filter prices.",
+      "properties": {
+        "amount": {
+          "description": "The price converted to Currency, in whole units. Approximate.",
+          "type": "number"
+        },
+        "currency": {
+          "description": "ISO 4217 code of the user's currency.",
+          "type": "string"
+        },
+        "rateDate": {
+          "description": "Date of the reference rate used, as YYYY-MM-DD. The European Central Bank's rate, or Frankfurter's for a currency the ECB does not publish.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "amount",
+        "currency",
+        "rateDate"
+      ],
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "excludesTax": {
+      "description": "True when the shop quotes this price before sales tax, as US shops do. Say so when you quote it.",
+      "type": "boolean"
+    },
+    "fromAbroad": {
+      "description": "True when no shop in the user's own customs area sells a bottle, so this is the cheapest bottle from a shop in another country that delivers to them.",
+      "type": "boolean"
+    },
+    "importChargesMayApply": {
+      "description": "True when the user may have to pay import charges on top of Amount. Say 'import charges may apply' when you quote it.",
+      "type": "boolean"
+    },
+    "pricePerMl": {
+      "description": "Amount divided by SizeMl, in Currency. USE THIS to compare value between fragrances priced in the same currency, never the bottle price - a small bottle can look cheap while costing far more per millilitre. Null when the size is unknown.",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "shipsFrom": {
+      "description": "ISO 3166-1 alpha-2 country the shop sells from, for example GB or US.",
+      "type": "string"
+    },
+    "sizeMl": {
+      "description": "Bottle size in millilitres that Amount applies to. 0 means the shop did not state a size.",
+      "type": "number"
+    }
+  },
+  "required": [
+    "amount",
+    "currency",
+    "sizeMl",
+    "pricePerMl",
+    "excludesTax",
+    "fromAbroad",
+    "shipsFrom",
+    "importChargesMayApply",
+    "estimate"
+  ],
+  "type": [
+    "object",
+    "null"
+  ]
+}

removedOutput schema / properties / results / items / properties / fragrance / properties / priceFromGbp

Removed value: -{
-  "description": "Lowest UK price we hold for a full-size bottle, in GBP. Excludes samples and decants. Null when we hold no full-size price.",
-  "type": [
-    "number",
-    "null"
-  ]
-}

removedOutput schema / properties / results / items / properties / fragrance / properties / pricePerMlGbp

Removed value: -{
-  "description": "PriceFromGbp divided by PriceSizeMl. USE THIS to compare value between fragrances, never the bottle price - a small bottle can look cheap while costing far more per millilitre. Null when the size is unknown.",
-  "type": [
-    "number",
-    "null"
-  ]
-}

removedOutput schema / properties / results / items / properties / fragrance / properties / priceSizeMl

Removed value: -{
-  "description": "Bottle size in millilitres that PriceFromGbp applies to. 0 means the retailer did not state a size.",
-  "type": [
-    "number",
-    "null"
-  ]
-}

changedOutput schema / properties / results / items / properties / fragrance / required

Previous value: -[
-  "slug",
-  "name",
-  "brand",
-  "brandSlug",
-  "concentration",
-  "yearLaunched",
-  "verdictBadge",
-  "verdict",
-  "keyNotes",
-  "priceFromGbp",
-  "priceSizeMl",
-  "pricePerMlGbp",
-  "imageUrl",
-  "scentArtUrl",
-  "url"
-]New value: +[
+  "slug",
+  "name",
+  "brand",
+  "brandSlug",
+  "concentration",
+  "yearLaunched",
+  "verdictBadge",
+  "verdict",
+  "keyNotes",
+  "price",
+  "imageUrl",
+  "scentArtUrl",
+  "url"
+]

First observedSep 21, 2026

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral context beyond that: each match carries a per-pair similarity score computed by ScentVerdict, the Cheaper direction ranks curated pairings first and then sub-anchor-price results, and prices are returned in the shop's own currency for the user's country.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is longer than most definitions, but front-loaded with purpose followed by usage, behavior and the exclusion rule. Most sentences earn their place; the closing price-currency sentence and the curated-pairings sentence add detail that could be tightened but is genuinely useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With four parameters, full schema coverage and an output schema that covers return values, the description supplies everything else an agent needs: when to call it, how `direction` behaves, what impacts price output, and which sibling to use instead. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3. The description goes further by explaining the semantics of `direction` (how results are steered away from the anchor, with concrete directions like cheaper/fresher/longer lasting) and what `country` affects (pricing in the shop's currency), adding meaning beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Find fragrances similar to one the user already knows') and explicitly differentiates itself from the sibling recommend_fragrances. An agent can tell it apart from search_fragrances and recommend_fragrances without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete when-to-use scenarios (cheaper alternative, budget version, gift for someone whose fragrance is known) and names the exclusion condition: use recommend_fragrances when the user names no anchor. This is explicit routing rather than implied usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ScentVerdict tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?