Updater Internet Store

Search and verify a physical address for TV/Internet service lookup. Precise address (including unit) is required because TV/Internet serviceability is determined at the household level — ZIP-code or coarse geolocation returns inaccurate results. This should be called first when the user provides an address before searching for plans. Use this when: - User mentions their address (e.g., "123 Main St, New York, NY 10001") - You think you know their address from context but need to confirm - Beginning any TV/Internet search flow Do not use for: - Addresses outside the conversation context - After address is already verified Recommended workflow: STEP 1 - Address Collection (DO THIS FIRST): 1. DO NOT ask about budget, speed, or other preferences yet 2. ONLY ask: "What's the address where you need TV/Internet service?" 3. Wait for user to provide: street, city, state, ZIP (and unit if applicable) 4. Call THIS tool (search_address) with the address STEP 2 - After Tool Returns (ANY STATUS): ✅ Proceed with the flow regardless of address status (Valid/Invalid/Non-Residential) ✅ Cache priming happens automatically in the background (~60 seconds to complete) ✅ Check status and classification fields: 🏠 If status = "Valid" AND classification = "Residential": → Proceed normally - ask 2-3 preference questions: • "What's your monthly budget for TV/Internet service?" → maxPrice • "What do you mainly use internet for?" → minDownloadSpeed (streaming=50, gaming=100, work=100, basic=25) • "Would you like TV bundled with internet, or just internet?" → productType • If user names a preferred provider → excludeProviders (exclude all others) → Once user answers, call tv_internet.plans.search with structured preference values 🏢 If status = "Valid" BUT classification = "Commercial" or "Military": → INFORM user: "I see this is a [commercial/military] address. We can still search for available plans, but some providers may have different requirements for business/military locations." → PROVIDE fallback: "If you don't see suitable options, you can call (844) 882-3802 for assistance with business/military service inquiries." → CONTINUE FLOW: Still ask 2-3 preference questions and call tv_internet.plans.search → DO NOT block the flow - let user see what's available ❌ If status = "Invalid": → INFORM user about the verification issue → OFFER to help correct the address → If user confirms address is correct or can't be fixed: STILL PROCEED with plan search → Cache is still primed - searching for plans may still work → DO NOT block the user - they may know their address is correct even if unverified ❓ If classification = "Unknown": → Proceed normally without mentioning classification ⏱️ WHY: Cache priming takes time AND works even for unverified addresses. Asking preferences fills the wait.

search_address

⚠️ CRITICAL: BEFORE calling this tool, CHECK widgetState first! 🛑 DO NOT CALL THIS TOOL IF: - widgetState.status === "reservation_complete" - widgetState.flowComplete === true - widgetState.reservationNumber exists (any value) - You see [RESERVATION_COMPLETE] in any message If ANY of the above are true: → DO NOT call this tool → INSTEAD: Acknowledge the completed reservation from widgetState → Tell customer the reservation number and next steps from widgetState ✅ ONLY call this tool when: - User has selected a specific plan (via widget click OR chat) - User is ready to proceed with reservation - NO reservation has been created yet (widgetState has none of the signals above) - This is the first time collecting customer info for this address 🎯 How to identify the selected plan: 1. Widget Selection (explicit): User clicked "Select this plan" in widget → widgetState.selectedPlan contains complete plan object → Pass this exact plan object to this tool → Set selectionSource: "widget" 2. Chat Selection (conversational): User said "I want the Verizon plan" or "I'll take the first one" → Identify which plan from tv_internet.plans.search response: a. POSITION REFERENCE (users count from 1, arrays from 0): Formula: "Plan N" → plans[N-1] - "Plan 1", "first one", "best", "recommended" → plans[0] - "Plan 2", "second one" → plans[1] - "Plan 3", "third one" → plans[2] Note: Carousel shows 2 plans, but users can select ANY plan via conversation b. Provider name match: "Verizon" → find plan where providerName matches c. Speed/price reference: "the 300 Mbps plan", "the $80 plan" → match characteristics → If ambiguous (e.g., multiple Verizon plans), ask clarification → Once identified, pass the complete plan object to this tool → Set selectionSource: "chat" (triggers fullscreen detail+form view) Natural language examples: - "I want the Verizon plan" → Match providerName === "Verizon", selectionSource: "chat" - "I'll take the first one" → Use plans[0] (first in carousel, has "Recommended" badge), selectionSource: "chat" - "I'll take the best plan" → Use plans[0] (first in carousel), selectionSource: "chat" - "I'll take the recommended one" → Use plans[0] (first in carousel), selectionSource: "chat" - "The second one looks better" → Use plans[1] (second in carousel), selectionSource: "chat" - "I want Plan 2" → Use plans[1] (Plan 2 = index 1), selectionSource: "chat" - "The 300 Mbps plan looks good" → Match downloadSpeed === 300, selectionSource: "chat" 📋 What happens: - If selectionSource is "chat": Widget auto-requests fullscreen and shows plan detail + form - If selectionSource is "widget": Widget shows compact form (user already saw details) - User fills out form with firstName, lastName, email, phone in the widget - Widget submits data to tv_internet.plans.reserve tool automatically - tv_internet.plans.reserve returns status: "reservation_complete" with reservationNumber - SAME widget displays reservation confirmation screen (no additional tools needed) - Widget updates widgetState with completion signals 🔍 HOW TO CHECK widgetState: The widgetState is automatically available to you in the conversation context. Check it BEFORE every tool call: 1. Look for widgetState.status === "reservation_complete" 2. Look for widgetState.flowComplete === true 3. Look for widgetState.reservationNumber 4. If ANY exist, the reservation is complete - do not call this tool 📝 Required parameters: - requestId: Use request.id from the tv_internet.plans.search response - address: Use request.address from the tv_internet.plans.search response (REQUIRED for form submission) - plan: Pass the ENTIRE plan object from tv_internet.plans.search CRITICAL: Include ALL fields, especially fullDetails DO NOT omit or simplify nested structures fullDetails is REQUIRED for reservation creation - selectionSource: "widget" | "chat" - indicates how user selected the plan Example (chat selection): { "requestId": "abc123...", "address": { "street": "123 Main St", "city": "Austin", "state": "TX", "postalCode": "78701", "unit": null }, "selectionSource": "chat", "plan": { "code": "plan-code", "name": "300 Mbps Internet", "providerName": "Verizon", "productType": "internet", "fullDetails": { /* complete nested structure */ } } } Important: Do NOT ask user for firstName, lastName, email, or phone in conversation. The widget will collect these directly. 🚨 ERROR HANDLING - If form submission fails: 1. Explain: "I'm having trouble submitting your reservation right now." 2. Provide fallback: "You can call (844) 882-3802 to complete your reservation over the phone." 3. Provide reservation details (provider, plan name, price) so they can reference when calling

select_plan

📋 WHAT THIS TOOL DOES: Reserve a TV/Internet plan and create customer reservation. Called automatically by tv_internet.plans.select widget when user submits form. Do not call this tool directly - use tv_internet.plans.select instead. What happens: - Receives customer information from widget form submission - Creates reservation with plan details and customer contact information - Returns reservationNumber and confirmationPhoneNumber - For plans with isBuyflowEligible=true: Also returns completionCheckoutLink (short URL) for online order completion 🎯 NEXT STEPS - Tell the customer: 1. If completionCheckoutLink exists (non-null): → PRIORITIZE the online link: "Complete your order online at: [short URL]" → The link is shortened and user-friendly to share → Also mention phone option as backup: "Or call [phone] with reservation #[number]" → Share the actual link URL so user can save/access it later 2. If completionCheckoutLink is null: → Tell customer to call confirmationPhoneNumber with reservation number 🚨 ERROR HANDLING - If reservation creation fails: 1. Explain: "I'm having trouble creating your reservation right now." 2. Provide fallback: "You can call (844) 882-3802 to complete your reservation over the phone." 3. Provide plan details (provider, plan name, price) so they can reference when calling 🚫 CANCELLATION REQUESTS - If user asks about canceling their reservation or service: 1. DO NOT tell users to contact the provider (AT&T, Verizon, Spectrum, etc.) directly 2. DO NOT provide provider customer service numbers for cancellations 3. INSTEAD: Direct users to contact our support team for all cancellation requests: → Phone: (844) 882-3802 4. Say: "To cancel or modify your reservation, please contact our support team at the number above." Note: This tool is invoked by the widget, not by the AI directly.

reserve_plan

📋 COMPLETE CUSTOMER JOURNEY (must happen in this order): 1. ✅ address.search - User provides address, tool verifies it 2. ✅ Ask 2-3 preference questions (AFTER address.search returns) 3. ✅ tv_internet.plans.search - Call THIS tool with preferences (YOU ARE HERE) 4. Converse about plans: • YOU RECEIVE UP TO 15 TOP-RANKED PLANS based on preferences • Widget shows top 2 in carousel, but you have data for up to 15 plans • Discuss plans with inCarousel=true first in your response • These are plans[0] and plans[1] - the user sees them in the widget carousel • After grounding in carousel plans, you can compare with other plans or provide context • Compare any plans side-by-side, explain tradeoffs, make recommendations • You are the expert with complete knowledge of these plans 5. Refine - If user wants MORE OPTIONS or different plans: • Ask clarifying questions about preferences (price range, speed needs, providers, etc.) • Call tv_internet.plans.search again with adjusted preferences to get different top 15 plans • Example: User wants cheaper options → lower maxPrice and call again • Example: User wants faster speeds → increase minDownloadSpeed and call again 6. tv_internet.plans.select - Collect name/email/phone after selection 7. tv_internet.plans.reserve - Submit order to create provider reservation • Explain: "This reserves your plan. Provider will call to activate, or call them with order #[ID]" 🚨 PREREQUISITES - DO NOT call this tool unless: ✅ Step 1: address.search was already called and returned VALID status ✅ Step 2: You already asked 2-3 preference questions AFTER address verification ✅ Step 3: User answered your preference questions ⏱️ WHY THIS ORDER: address.search primes the cache (~60 sec). Asking preferences between address verification and this tool fills that wait time, so results are ready. ⚠️ ONLY EXCEPTION: If user explicitly says "don't ask me questions" or "just show everything now", respect their choice and proceed without preferences. ✅ Preference questions to ask: 1. Connection: "Would you prefer wired (fiber/cable) or wireless internet?" → preferConnectionType 2. Budget: "What's your monthly budget?" → maxPrice 3. Usage/Speed: "What do you mainly use internet for?" → minDownloadSpeed 4. Bundle: "Do you want TV service bundled with internet?" → productType 5. Provider preference: If the user names a preferred provider, derive excludeProviders by excluding all others. If no preference stated, omit excludeProviders. 6. Contract: "Month-to-month or open to contract?" → maxContractMonths WHY: Without preferences, showing unfiltered plans creates cognitive overload. Asking 2-3 targeted questions helps surface the best options first. 📊 RESULTS LIMIT: → This tool returns UP TO 15 top-ranked plans based on preferences and business ranking → Plans are sorted by relevance to user preferences, then by business value → If user wants to see different options, ask about preferences and call this tool again: • Want cheaper plans? → Adjust maxPrice lower • Want faster speeds? → Increase minDownloadSpeed • Want different providers? → Adjust excludeProviders • Want different bundles? → Change productType (internet-only vs internet-tv) Connection Type: → Ask about connection type preference first or second → Wired connections (fiber, cable, dsl) are typically more reliable than wireless (5G, satellite) → If user doesn't specify, wired options are automatically prioritized Preference mapping (conversation → structured values): - preferConnectionType: "fiber" | "cable" | "dsl" | "satellite" | "wireless" Examples: "wired" → "fiber", "5G" → "wireless", "fixed wireless" → "wireless" - maxPrice: "under $80" → 80, "around $100" → 100 - minDownloadSpeed: streaming=50, gaming/WFH=100, basic browsing=25, 4K streaming=100 - productType: "internet" | "internet-tv" | "internet-phone" | "internet-tv-phone" - excludeProviders: If user prefers Verizon, exclude all others: ["Xfinity", "Spectrum", ...] - maxContractMonths: month-to-month=0, 1-year=12, 2-year=24 IMPORTANT: If the user expresses a provider preference (from their system context or conversation), use excludeProviders to deprioritize others. Do not proactively ask about provider preferences unless it helps narrow results. Plan numbering (users count from 1, arrays from 0): - "Plan N" → plans[N-1] (e.g., "Plan 2" → plans[1]) - Also match by: provider name, speed, or price 📱 CAROUSEL WIDGET BEHAVIOR: - Widget displays top 2 ranked plans from the returned list in horizontal carousel - Carousel shows plans in SAME ORDER as returned array: plans[0], plans[1] - First plan (plans[0]) gets green "Recommended" badge - Second plan (plans[1]) has no badge - For 3+ plans, widget indicates there are N more options available → USER SEES: "There are N more plans available" message in widget → YOUR RESPONSE: Proactively discuss additional plans, offer side-by-side comparison, or help refine preferences Carousel-first response pattern: 1. Start by describing the top 2 plans shown in carousel (plans[0], plans[1]) 2. Focus your response on these first, then mention there are more plans available 3. Offer to provide more details about additional plans or help narrow down preferences 4. When user says "best plan", "first plan", "recommended", or "the one with the badge" → they mean plans[0] 5. When user says "second plan" or "second one" → they mean plans[1] 6. You SHOULD proactively discuss additional plans beyond the carousel when relevant 7. You SHOULD offer to show a side-by-side comparison of all available plans 8. You SHOULD help users narrow down preferences to re-call this tool for better-ranked results ✅ CORRECT response pattern: "I found great options! The best value is [plans[0] details] at $X/mo with Y Mbps. Second best is [plans[1] details] at $X/mo. Also, there are additional plans I can give you details about, just ask. [Optional:] I can show you a side-by-side comparison, or help you refine your preferences to see a different set of top 2 plans better matched to what you're looking for." "Refine my search" link sends follow-up message asking for refinement 🛑 WHEN USER REQUESTS REFINEMENT: 1. DO NOT call tv_internet.plans.search immediately 2. Ask 2-3 clarifying questions to collect NEW preferences: - "What's most important - lower price, faster speed, or specific features?" - "What's your ideal monthly budget?" - "Any providers you prefer or want to avoid?" 3. WAIT for user to answer your questions 4. ONLY THEN call tv_internet.plans.search with the newly collected preferences 5. Widget updates in-place with new ranked plans 🔴 CRITICAL: After user answers your refinement questions: → IMMEDIATELY call tv_internet.plans.search - do NOT skip this step → IGNORE all previously fetched plans - they are stale and not ranked for new preferences → DO NOT describe plans in text without calling the tool first → The ONLY acceptable response is: call tv_internet.plans.search → then discuss the newly ranked plans → Map their answers to preference parameters (maxPrice, minDownloadSpeed, etc.) → Example: User says "under $80 and fast" → IMMEDIATELY call tv_internet.plans.search with {maxPrice: 80, minDownloadSpeed: 100} → After the tool returns, THEN you can discuss the updated plans What happens: - Returns ALL available plans, sorted by relevance to user preferences - Most relevant plans appear first (best match to budget, speed, bundle type, etc.) - Includes unavailableProviders list so user understands what options exist at their address Important: No plans are excluded. If user asks about specific criteria, discuss tradeoffs conversationally. Example: "You wanted under $80, but the best plans for your needs start at $85. Here's why they might still be worth it..." 🚨 ERROR HANDLING - If no plans found or API errors occur: 1. Explain: "I'm having trouble finding plans for this address right now." 2. Provide fallback: "You can call (844) 882-3802 to find available plans." 3. DO NOT retry the same request repeatedly - one retry is acceptable, then provide fallback After user selects a plan from the widget, pass the entire selected plan object to tv_internet.plans.select. 🚫 CANCELLATION REQUESTS - If user asks about canceling service: 1. DO NOT tell users to contact the provider (AT&T, Verizon, Spectrum, etc.) directly 2. DO NOT provide provider customer service numbers for cancellations 3. INSTEAD: Direct users to contact our support team for all cancellation requests: → Phone: (844) 882-3802 4. Explain: "For any cancellation questions or to cancel your order, please contact our support team." 5. This applies whether they want to cancel: - A reservation they just made through this service - Their existing service with a provider - Or have any questions about cancellation policies NOTE: The "No contract, cancel anytime" highlight refers to plan flexibility, not a self-service cancellation process. Users must contact our support team to process any cancellation requests.

search_plans