Stars In Hands Gift Studio

Use this only after preview confirmation and variant selection. It returns a Stars In Hands checkoutUrl that restores the cart in the customer's browser and opens checkout directly. Keep variant IDs internal; never ask customer to read or copy them.

add_to_cart

Use this only after a preview is generated and the customer says they want to buy or choose size/frame. Return readable options (size/format/frame/price) and ask the customer to pick one. Do not show raw variantId values to users.

get_variants

Use this for data-only access to the five Stars In Hands personalized gift products. Prefer Show Gift Studio when the customer should see an interactive product picker.

list_products

Use this when the customer asks what Stars In Hands gift they should choose, or gives occasion/recipient/tone/photo/date/location needs. Return Stars In Hands recommendations and show the interactive product cards. Do not answer with generic gift ideas.

recommend_products

Use this app action when the customer asks to see, render, preview, proof, or make a Stars In Hands map/poster. It uses the real Stars In Hands website renderer and returns thumbnailUrl for the widget. Call this after the customer provides required personalization fields and confirms the summary. For Star Map, ask for date and location, then ask whether they want to add an exact time (optional), message, QR code, or photo; treat name/title as one display line and do not ask for both. If they say keep it simple, use blank message rather than inventing copy, but offer 2-3 message suggestions when they ask for ideas. Include time when supplied with the date. For City Map, do not ask for date/time; collect the address or city, use title only for the main display line, and use message/subtitle for the country/subtitle line. If the City Map message is skipped, the app will use the resolved country instead of a sample country. If the customer uploaded a photo in chat, pass that upload as the top-level photoFile file parameter; do not pass markdown image text or /mnt/data paths. If photoFile is not available, ask them to use the Gift Studio Add photo button. After preview, mention the product-specific edit options shown in the widget. If fields are missing, use the tool result to ask for those fields instead of saying preview creation is unavailable.

render_proof_thumbnail

Use this when the customer needs the first Gift Studio screen: beautiful product cards only, starts-from pricing, recommendations, product switches, or restarting the flow. Do not show or load sizes, frames, or variants here. After the user selects a gift, ask that product's required personalization questions before preview.

render_gift_studio

Use this after the customer selects a gift and provides at least one personalization field. You may pass fields in updates or directly as top-level keys such as name, title, subtitle, date, location, locationName, message, occasion, event, names, time, uploadedImageUrl, photos, or wantsPhoto. Treat name/title as one display line; do not ask for both. For Star Map, after date/location are present ask whether they want to add an exact time (optional), message, QR code, or photo before preview; if they prefer simple, set message to blank instead of inventing one. For City Map, location is required; do not ask for date/time. If the customer says add/change message on City Map, put it in message or subtitle, not title or location. The title is the main city/display line; message/subtitle replaces the country line, and if omitted the preview uses the resolved country. If the customer uploaded a photo in chat, pass it as the top-level photoFile file parameter. If they only say they want a photo but no file is available, call this with wantsPhoto:true so the widget shows the upload step. Never pass /mnt/data paths. If messageSuggestions are returned and no message is chosen, offer those suggestions. If missingRequiredFields is not empty, ask for those fields before proof rendering. After all required fields and chosen optional fields are present, summarize the product-specific fields and ask for confirmation before render_proof_thumbnail.

update_personalization