---
name: inspired-visual-search
description: Shop a photograph with Inspired — name every purchasable object in an image, cut each one out, and return where to buy it. Use when the user shares a photo and wants to find, buy, price, or source what is in it ("where can I get this", "find me this outfit", "shop this room", "what is that lamp"), or asks to enrich a product image into shoppable links. Covers choosing a focus domain, starting a durable read, polling it, and reporting results honestly.
---

# Shop a photograph with Inspired

Inspired reads one image, cuts every separately purchasable object out of it,
and returns retailer links per object. This skill is how to drive it without
wasting the user's allowance or overstating what came back.

## Before you start

You need an Inspired API key in the environment or configured on the MCP
connection. If there is no key, say so and point the user at
`https://inspired.jetskibay.com/docs` — do not attempt the call.

Check which surface you have:

- **MCP tools** named `list_focus_domains`, `start_visual_search`,
  `get_visual_search`. Prefer these.
- **HTTP**, at `https://inspired.jetskibay.com/api/v1`, with the key as
  `x-api-key`. Use `POST /api/v1/jobs` and `GET /api/v1/jobs/{id}`.

Never use `POST /api/v1/inspire`. It holds the connection for the whole read and
will time out.

## The three facts that shape everything

1. **A read takes minutes.** One vision call, then one extraction per object
   strictly one at a time. Six objects is the slow case. Do not wait in a tight
   loop and do not tell the user it will be quick.
2. **Starting a read costs one request; polling is free.** A trial key has ten.
   So: never start a second read for the same image, never "retry" a read that
   is still running, and never re-mint a key to get more allowance — re-minting
   carries the old balance over rather than resetting it.
3. **Nothing is verified.** No stage re-checks a cutout against the original
   photo and nothing scores how close a retailer match is. This constrains the
   words you may use when reporting; see below.

## Workflow

### 1. Choose the focus domain

The domain decides what the reader looks for. It is the one decision that makes
a read useful or useless, and the default is `fashion`, which is wrong for most
non-outfit photos.

| Photo of | Use |
| --- | --- |
| A person, an outfit, shoes, a bag | `fashion` |
| A room, sofa, table, lamp, rug | `furniture` |
| A desk, laptop, headphones, camera, appliance | `devices` |
| Bottles, jars, makeup, fragrance, haircare | `beauty` |
| Anything else, or a mixed scene | `everything` |

When you are unsure, call `list_focus_domains` (free, no allowance) rather than
guessing. Aliases such as `tech`, `home` and `any` also resolve.

Add `focus` — up to 160 characters — to narrow within a domain, for example
`domain: everything`, `focus: kitchen appliances only`. Use it to narrow, never
to redefine: the text is appended as one clause and cannot override the reader's
instruction.

An unknown domain is refused with a `400` and nothing is charged. If that
happens, you sent a typo — fix it and call again.

### 2. Start the read

Send the image once. Over MCP:

```json
{
  "name": "start_visual_search",
  "arguments": {
    "image": "<base64 of the file, or a data: URL>",
    "imageMediaType": "image/jpeg",
    "domain": "furniture"
  }
}
```

JPG, PNG, WEBP or GIF up to 10 MB. Resize a large photo before sending — a
2048px longest edge is plenty. Instead of bytes you may send `pinterestUrl`
with a public pin URL. Send exactly one of the two.

Keep the `requestId`. It is the only handle on the read, and only your key can
collect it.

### 3. Collect it

Call `get_visual_search` with the `requestId`. While it runs you get
`status: "running"` and a per-object progress list. Wait the `pollAfterMs` it
returns — 3000 today — between calls.

Tell the user what is happening once, with the object names as soon as the read
reports them, then stay quiet until it finishes. A named list filling in is
reassuring; a progress message every three seconds is noise.

If it is still running after several minutes, say so and keep the `requestId`.
It stays valid. Do not start again.

### 4. Report the result

For each object: its name, the description of what was actually visible, and its
best matches with prices and links. Lead with the objects the user asked about.

Keep the candidate order. It is Google Lens's own product-mode ordering,
price-led, and there is no similarity score in the response to improve on. If
the user wants the cheapest, say which one is cheapest; do not silently re-rank.

## Expected outputs

A short report, one block per object:

```
Floor lamp — slim brass floor lamp with a white cone shade, round weighted base
  €149  Brass arc floor lamp        https://shop.example/brass-arc-lamp
  €189  Tall brass reading lamp     https://shop.example/reading-lamp
Sofa — three-seat sage boucle, straight arms, tapered wooden legs
  €899  Boucle three-seater, sage   https://shop.example/boucle-three-seater
Rug — flatweave oatmeal with a narrow charcoal border
  no matches found
```

Plus one sentence of honest framing, and the cutout image URLs if the user can
use them.

## The words you must use

The pipeline performs no verification, so:

- Objects are **spotted**, not *identified*, *detected* or *recognised*.
- Retailer results are **visually similar**, not *the same product*, *exact*,
  *a match* or *found*.
- An object with no results found nothing similar enough — do not substitute
  another object's results to fill the gap.

If the user is about to spend real money, say that the link is a lead and they
should check the retailer page themselves.

## Handling the awkward cases

**Empty result.** `items: []` with a summary is a successful read: nothing in
the photo was clearly enough visible to shop for. Report that, suggest a better
photo — lit, in frame, the object not mostly hidden — and note it did cost one
request. Do not retry the same image hoping for a different answer.

**Wrong objects.** If it returned cushion covers and the user wanted the sofa,
the domain was probably wrong. Say what you think happened, and ask before
spending another request on a re-run.

**`quota_exhausted`.** The key's requests are used up. Stop. Tell the user how
to get another key. Do not mint one to work around it.

**`404` on a collect.** Either the id is wrong or the read belongs to another
key. The response cannot tell you which by design. Check the id you saved; do
not retry in a loop.

**A failed read.** `isError: true`, or `status: "failed"` over HTTP. The request
was refunded. One retry is reasonable; two is not.

## Limits

- 6 objects per read, 10 matches per object.
- The mood board and cutouts: over MCP these are HTTPS URLs; over HTTP they are
  base64 `data:` URLs. Candidate images are hosted by retailers and by Google
  and will expire.
- No brand is named unless a brand mark is clearly legible.
- Inspired accepts image bytes or a Pinterest pin URL. There is no parameter
  that fetches an arbitrary image URL, so you cannot hand it a link to a photo
  on the web — download it first.
- Everything here describes the platform as deployed in September 2026 at
  `inspired.jetskibay.com`.

## Installing this skill

Copy `inspired-visual-search/SKILL.md` into your agent's skills directory — for
Claude Code, `.agents/skills/inspired-visual-search/SKILL.md` in the repository
or `~/.claude/skills/inspired-visual-search/SKILL.md` for every project — and
start a new session so it is discovered. It is a single file with no supporting
scripts. Nothing installs itself; nothing here executes on its own.