Tonita

A list of listing IDs to retrieve details for. **How to use:** Pass the listing IDs from a previous `tonita-search` result. Each listing in the search results has a `listingId` field — collect the ones you need and pass them here. **Why this matters:** This is the only way to get full product details (description, all images, sizes, URL) and the `image_id` needed for visual search. **Rules:** - Maximum 10 listing IDs per call in normal use. - IDs must come from a previous tonita-search result. **Example:** ['thursdayboots.com!6c66be1f3d6c7f00', 'nike.com!a1b2c3d4e5f67890']

The target gender for the product. **How to use:** Pick the value that best matches the shopper's intent from: Mens, Womens, Kids, Boys, Girls, Gender-Neutral, Unknown. **Why this matters:** Gender is woven into every retrieval and ranking query. Setting it correctly prevents the search engine from wasting retrieval slots on the wrong half of the catalog. **Rules:** - Use 'Gender-Neutral' when the product category is not gendered (e.g., phone cases, tote bags). - Use 'Unknown' only when the shopper has not indicated a preference and the product is gendered. **Examples:** 'Womens' for 'women's summer dress', 'Mens' for 'men's running shoes', 'Kids' for 'children's rain boots'

The specific type of product to search for. **How to use:** Set this to a single, narrow product category. Use the most specific term that fits — 'running shoes' rather than 'shoes', 'midi dress' rather than 'dress' — when the shopper has been specific. **Why this matters:** The search engine uses product_type to filter the catalog and construct retrieval queries. A vague type like 'clothing' returns unfocused results because the catalog is organized by specific categories. **Rules:** - Must be a single product type. To search for shirts AND pants, make two separate tool calls. - Never use 'clothing', 'apparel', or 'outfit'. - Do not include adjectives — product_type is the category, not the description. **Examples:** 'dress', 'running shoes', 'denim jacket', 'crossbody bag', 'sunglasses', 'bikini top', 'cargo pants'

The main search query describing what the user is looking for. This will be used for ranking results.

One or more search queries used to retrieve candidate products from the catalog. **How to use:** Write concise, objective, natural-language descriptions of the desired product. Each string is run as an independent retrieval query; candidates are pooled before ranking. Use multiple entries to broaden recall (different synonyms or phrasings for the same intent). **Why this matters:** These queries drive which products enter the candidate pool. Clear, literal wording produces much better results than vague or pop-culture phrasing. **Rules:** - Keep each query objective and literal. - Never reference other products (e.g., 'similar to the Patagonia jacket'). Describe attributes directly. - Use at most 5 queries for text search. - When `prioritize_visual_similarity` is true, use exactly ONE query that captures the visual essence of what the shopper wants. **Good examples:** ['white women's low-top sneakers; leather upper; minimalist design'], ['men's navy blue wool overcoat'] **Bad examples:** ['shoes for hot girl walks'], ['something like the Nikes I saw earlier']

Additional query variations to improve retrieval coverage. These are different phrasings of the same intent.

A short display title for the search results. Falls back to the first `retrieval_queries` entry if omitted. **How to use:** Write a concise, shopper-facing label that summarizes the results — like a carousel heading. **Examples:** 'Red dresses under $100', 'Nike running shoes', 'Bags similar to your selection'

The desired color of the product, as a human-readable name. **How to use:** Set this to the color the shopper wants. Use simple, standard color names. If the shopper has no color preference, leave this null. **Why this matters:** The color name is woven into the retrieval and ranking queries, helping the search engine favor products described with that color in their title and metadata. **Examples:** 'red', 'navy blue', 'forest green', 'black', 'cream', 'burgundy'

The desired color as a 6-digit RGB hex code (e.g., '#FF0000' for red). **How to use:** When you know the exact color (for example, from a previously shown listing's metadata), pass it here. If the shopper just says 'red' and you don't have an exact hex, you can either pick a representative hex or leave this null and rely on `color` alone. **Why this matters:** The search engine uses this hex code to visually rescore results — products whose images are closer to this color get a ranking boost. This is more precise than the text-based `color` field because it operates on actual pixel data from product images. **Examples:** '#FF0000' (red), '#000000' (black), '#1E3A5F' (navy blue), '#228B22' (forest green)

Brands to exclude from the search results. **How to use:** Set this when the shopper explicitly says they do NOT want products from certain brands. Leave null if no brands to exclude. **Why this matters:** Excluded brands are factored into the reranking query so those products rank lower. **Example:** ['SHEIN', 'Temu']

Retailer domains (websites) to exclude from results. **How to use:** Set this when the shopper explicitly says they do NOT want products from certain retailers. Use domain names (e.g., 'amazon.com'). Leave null if no retailers to exclude. **Why this matters:** This sets a hard filter — no products from these domains will be returned, regardless of how relevant they are. **Example:** ['amazon.com', 'walmart.com']

Brands to include in the search results. Set to null if no brand preference.

Retailer domains (websites) to include in results. **How to use:** Set this when the shopper explicitly wants products only from certain retailers. Each value must be a domain name (e.g., 'nike.com'), not a display name (e.g., NOT 'Nike'). Invalid domains are silently ignored. Leave null if no retailer preference. **Why this matters:** This sets a hard filter on the search results — only products from these domains will be returned. Use the domain list from the system instructions to find valid domain names. **Rules:** - Use domain names, not brand names (e.g., 'nordstrom.com' not 'Nordstrom'). - 'Show me similar items' does NOT mean same retailer. **Example:** ['nordstrom.com', 'zappos.com']

The shopper's price constraints, as a natural-language string. **How to use:** Express the price preference the way the shopper did. If the shopper has no price preference, leave this null. **Why this matters:** Price is woven into the reranking query so results favor products in the right range. This is a soft preference, not a hard filter. **Examples:** 'under $50', 'between $100 and $200', 'around $75', 'under $500', 'luxury price range'

Whether to prioritize visual similarity over text-based relevance (matches chat `prioritize_visual_similarity`). **How to use:** Set to true when the shopper wants products that LOOK LIKE a reference image or a previously shown product. Must be used together with `query_images`. **Why this matters:** When enabled, visual similarity scores drive ranking more than text matching. **Rules when true:** - You MUST also provide `query_images`. - Set `retrieval_queries` to ONE query capturing the visual essence of what the shopper wants. - Keep `reranking_query` very simple (basic category/features). **Example:** User says 'more shoes like this'. After `tonita-get-listing-details`, call `tonita-search` with retrieval_queries=['minimal white leather sneaker'], prioritize_visual_similarity=true, query_images=[{"image_id": "89e667d28336d70f"}]

Images for visual retrieval (matches chat `query_images`). **How to use:** Provide one entry per reference image using exactly one of: - `image_id` — from `tonita-get-listing-details` (`thumbnail_image.image_id`) when referencing a prior result - `base64` — when the shopper attached a photo - `url` — when you have a direct HTTPS link to a product photo You can include up to 5 images. **Why this matters:** The search engine encodes these images and retrieves catalog items whose product photos are visually similar. **Rules:** - Always set `prioritize_visual_similarity` to true when providing query images. - Use exactly one `retrieval_queries` entry for visual search. **Examples:** - Catalog: [{"image_id": "89e667d28336d70f"}] - User photo: [{"base64": "data:image/jpeg;base64,/9j/..."}] - URL: [{"url": "https://cdn.example.com/shoe.jpg"}]

A detailed query used specifically for ranking/scoring the retrieved candidates. Falls back to the first `retrieval_queries` entry if omitted. **How to use:** When the shopper's intent has nuances that matter for ranking but would hurt retrieval, express them here. Use semicolons to separate sub-phrases. **Why this matters:** Retrieval queries should be broad to catch all relevant products. The reranking query can be more specific to push the best matches to the top. **When `prioritize_visual_similarity` is true:** Keep this very simple (basic category/features only). Over-constraining suppresses strong visual matches. **Example:** retrieval_queries=['summer dress'], reranking_query='floral wrap dress; summer weight fabric; midi length; feminine silhouette'

Brands to restrict results to. **How to use:** Only set this when the shopper has explicitly asked to see specific brand(s). If the user says 'show me Nike shoes', set this to ["Nike"]. If they have no brand preference, leave null. **Why this matters:** Brand names are added to retrieval queries and brand filters tighten which products can appear. **Rules:** - Only populate when the shopper explicitly wants specific brands. - 'Show me similar items' does NOT mean same brand — don't auto-populate from a referenced listing's brand. **Example:** ['Nike', 'Adidas', 'New Balance']