HeyYumi

Ask the venue's owner a RIGHT-NOW question by pushing it to their phone. REAL side effect: it notifies the owner, who has a 5-minute window to answer. SPEED (avoid a needless round-trip): call this DIRECTLY — do NOT call search_live_status first. In ONE call the server itself reuses a fresh owner-verified answer if one exists (returns reused:true, no new push), attaches you to an in-flight identical ask, AND blocks off-hours (returns blocked:'closed_now', see below) — so a separate pre-check only wastes time. Let the server decide; don't gate this on business hours yourself. Only venues with an active owner (Yumi app) can be asked; otherwise you get live_status_not_available — then DON'T retry, tell the user we can't check live for that place (offer to call). Pick kind: 'item' = is X in stock / did today's item come in / sold out (A,B,C); 'wait' = current wait time (D); 'seats' = can they get in / seat a party right now, incl. large groups like 10 people (E). Give topic as a bare token (e.g. '두바이 쫀득 쿠키', '웨이팅', '10명 입장'). kind='item' — ask about THAT venue's real menu: use a menu name you saw in get_place (menu/menuSummary) as the topic. Don't ask about an item the venue doesn't sell (annoys the owner and wastes the 5-min window). If unsure it's on the menu, call get_place first. kind='seats' for a party of ANY size (incl. large like '10명 바로 돼요?') — ask ANY venue with an active owner; do NOT pre-filter by seat count or venue size. Lots of places seat a group without a formal group room (고깃집 push tables together; cafes often say yes to 10 people), and the owner just answers 됩니다/안됩니다. Over-filtering by 'has group seating' loses real opportunities, so don't gate on it. ALWAYS include the party size in a seats question — a bare '지금 자리 있어요?' is NOT answerable (the owner would just ask '몇 명이세요?', because seats for 2 vs 10 is a totally different answer). If the user didn't say how many people, ASK them the headcount FIRST, then send topic like '10명 즉시 착석' (put the number in). The owner may answer 'limited' with a note like '따로 앉으시면 돼요' or '10분 뒤 가능' — relay that note. kind='wait' — the owner may answer 'limited'/'unavailable' WITH a wait time in `note` (e.g. '약 20분', '앞에 3팀'); always relay that note, not just 'there's a wait'. CLOSED NOW: every live question is about RIGHT NOW, so if the venue is currently OUTSIDE its confirmed business hours the server returns {blocked:'closed_now', openNow:{open:false,reason}, note} WITHOUT pushing the owner (we don't wake them at 3am). When you get this, do NOT retry and do NOT wait_for_live_status — just tell the user the shop isn't open right now (use openNow.reason and its business hours from get_place) and offer to check once it opens. (Unknown hours are NOT blocked — the owner is still asked.) The response starts as status 'pending' — NOT answered yet. Tell the user you're checking with the shop and it takes up to 5 minutes, then call wait_for_live_status with the returned queryId and keep calling until settled. If the same thing is already being asked, you'll be attached to it (interestedCount rises = '지금 N명이 찾는 중') — that's expected. This is a PRE-CHECK that gates the next action, not a visit-only question. When the answer is positive, chain into the action: seats 'available' + the user wants to book → call request_reservation (this live check is the pre-step to a booking); item in stock → tell them they can head over / buy it now. This tells you if the shop is DOING something (has the item / seats now), NOT a guarantee — stock can change; always relay the owner's answer with its verified time and add that quantities may change on the way.

request_live_status

Dataset coverage stats: total places, regions covered, multi-source share, average confidence. Use to answer "how much data do you have?" or to set expectations about coverage (expanding across Korea — strongest in Seoul, Gyeonggi and Jeju, other cities partial).

get_stats

Check a live question's status ONCE (no waiting), by its queryId. For a fresh question you're waiting on, prefer wait_for_live_status (it blocks until the owner answers). Statuses are the same as wait_for_live_status. 'no_response' = owner didn't answer in 5 minutes.

get_live_status

Fetch full detail for one venue by its canonical id (from a search_places / nearby_places result). Use this when the user wants more about a specific place already found. The fields mask controls how much detail you get and how many tokens it costs. RESERVATION STATUS: to report whether a venue can be booked, request a fields mask that includes contact_hours (it returns `reservationChannels` and `yumiReservable` plus `bookingUrl` and `phone`), then state which case applies: (1) channels include "yumi" (yumiReservable=true) → the venue is a Yumi partner and can be booked in this chat via request_reservation. PROACTIVELY surface this even when the user hasn't asked to book — as you introduce the place, add '이 집은 유미 파트너라, 원하시면 이 채팅에서 바로 예약 요청을 보내드릴 수 있어요' (it raises how often people actually book). Say 예약 요청(request), NOT '바로 예약돼요'/예약 확정 — the owner must accept it first. To proceed, collect the guest's name, phone number (always — the owner uses it to reach them; foreign visitors give their own international number), and — for a NON-Korean number ONLY — also an email in the SAME step (that's how a foreign guest gets the outcome + view/cancel link, since we can't text international numbers; a Korean guest needs phone only, do NOT ask them for an email), plus date & time and party size, then call request_reservation. (2) channels are "external"/"phone" only → booking exists but only via that link or phone number; say which one instead of a vague "예약 가능". (3) `reservationChannels` is EMPTY → we could not confirm a booking route (that means UNKNOWN, not "walk-in only") → tell the user it needs checking with the venue; only say walk-in if there is no phone and no booking link at all. NEVER promise availability: even for a Yumi partner, "그 시간에 영업한다"는 확인된 사실이고 "자리가 있다"는 아니다 — a table for N people is confirmed only when the owner accepts the request_reservation (use wait_for_reservation). There is no party-size filter anywhere in this API, so never state that a venue can seat a given number of people. CLOSURE RISK: `possiblyClosed` is in core (always returned). If true, an unconfirmed government closure signal is attached — warn the user this place may have closed and to confirm before visiting; request fields="quality" for `closureSignal` (reason + government closure date) if they want specifics. FRESHNESS: request quality for `freshnessScore` (0–1) or edge for `reputation` (`recently_active`, `last_verified_days_ago`, caveats). If freshness is low / recently_active=false / last_verified_days_ago is large, tell the user the details (especially hours & price) may be outdated and worth confirming — a soft caution, not a closure. CONCERNS: if `reputation.concerns` is non-empty, quote each item's Korean `note` sentence as-is — it already contains the honest denominator ("최근 리뷰 38건 중 4건에서 …"). NEVER print the raw tag or generalize it into a label like '불친절한 곳'/'위생이 안 좋은 곳': these are minority mentions that cleared a strict bar (2+ sources, 3+ mentions, ≥10% of reviews read), and this is a real business whose owner is affected by how you phrase it. The denominator is `sampleSize` (reviews we read), never `reviewCount`. An empty/absent concerns list means nothing cleared that bar — not that the place is perfect. SOURCE ATTRIBUTION & NO STAR RATING: `reviewCount` is an unlabeled fact — NEVER attribute it to a specific platform (no '카카오 리뷰' / '네이버 리뷰') and don't name or guess which map service it came from; present it plainly as the venue's own reviews. We NO LONGER publish a star rating: `rating` is null on every venue by policy (별점은 조작 가능성이 높고 사장님에게 불리해 폐기했다), so a null rating is EXPECTED and NOT a data error — never invent, infer, or web-search a star score. Show popularity via `reviewCount` alone (e.g. '리뷰 604건'), which is the highest review count we saw across sources. INFLUENCER: `influencerFeatures` (edge, returned by default; present ONLY when a consented ambassador featured this venue) is a list of {platform, account, profileUrl, featuredAt, dishes, contentUrls}. You MAY add that the place was introduced by them — e.g. '이 집은 인스타그래머 @newly_cafe.eat 님이 소개한 곳이기도 해요' (say 유튜버 for platform="youtube", 틱톡커 for "tiktok"), and name the featured `dishes` if present. `contentUrls` is a list of {url, postedAt} (the post/video + its upload date). If non-empty, SHARE the first `url` as a clickable markdown link so the user can watch it — e.g. '📸 소개 영상 보기: [@newly_cafe.eat](<contentUrls[0].url>)' — this video/photo is what hooks people into visiting. A ready-made `influencerContent` line (handle · link · date) is also attached whenever a link exists — post that link verbatim, do not just say '링크가 있어요'. You MAY mention `postedAt` ('2026년 6월 소개 영상'). Links older than ~1 year are already dropped server-side (their menu may have changed), so `contentUrls` only ever holds recent posts — when it is empty, still credit the introduction ('예전에 @X 님이 소개한 곳') but do NOT invent, guess, or web-search a link. You may also share the `profileUrl` as a link. Say '소개한 곳' ONLY — NEVER frame it as an endorsement/guarantee ('@X가 보증하는 맛집'/공인 ✗): it is a fun discovery signal, NOT a trust basis, and must not override cross-source verification or outweigh concerns/closure/freshness. Absent/empty = no consented feature (NOT a negative signal). CUISINE MISMATCH (간판 ≠ 메뉴): `categoryLabel` is the raw label from the venue's origin, not our judgement. If `serviceAttributes.classification_conflict` is present (edge), the label and the real menu disagree — the menu is overwhelmingly `menu_suggests` (share = `menu_share`), so we either removed the venue from that cuisine's searches (`action: "demoted"`) or reclassified it (`"reclassified"`). Describe it by the MENU, and say the mismatch plainly ('간판은 한식이지만 메뉴는 파스타·피자 중심이에요') instead of repeating the label. PRICE: `price` = {level, avg, min, max} from menu prices with add-ons (공깃밥·사리·추가) excluded. null `level`/`avg` = UNKNOWN (too few priced items) → do not say cheap/expensive, and treat min/max only as 'a menu item at that price exists'. Prices are per DISH, not per person — shared dishes (족발·전골·모둠) look premium for one; never convert them into '1인 X원'. VEGAN / DIETARY (a vegan drink is not a meal): request fields="dietary" (or edge) for `dietary` = {fully_vegan, vegan_options, vegetarian_options, mixed_group_suitable, vegan_menu_count, vegan_main_count, non_vegan_menu_count, confidence, note}. `vegan_main_count` counts vegan MEALS (drinks like 비건 오트라떼 excluded) — if it is 0 while `vegan_menu_count` > 0, the only vegan items we confirmed are drinks, so do NOT offer the place as somewhere a vegan can eat. If `owner_declared` is true, the OWNER confirmed it in our partner app and the counts may be missing entirely — that is the strongest evidence, so say the owner confirmed it instead of reading absent counts as 0. Name the actual vegan dishes from `menu` so the user can verify, quote `note` as-is, and always add that shared cooking surfaces/utensils must be confirmed with the venue (we cannot know that). These counts are what we could confirm from the menu, not a guarantee. WHEELCHAIR: `serviceAttributes.wheelchair_accessible=true` (edge) = 휠체어 가능으로 확인된 곳 — say exactly that, plainly. It is ONE boolean and there is nothing behind it: we have no data on 출입구 단차, 엘리베이터, 통로 폭, 장애인 화장실 or 휠체어 좌석, so never describe the setup or imply step-free access, and never say where the value came from. Add that those exact conditions are worth confirming with the venue directly. An absent flag = UNKNOWN, not '휠체어 불가'. PHOTOS: whenever the user wants to SEE the place — '사진 보여줘', '내부/외관 어때', 'what does it look like', or is deciding based on looks — prefer the dedicated `show_place_photos` tool (it returns the actual images). If you instead use this tool, include "photos" in the fields mask (NOT in the default); the returned `photos` (main + gallery[] with category exterior/interior/seating/room/mood/restroom + menu[] + menuBoard) are the OWNER's verified images of THIS exact venue. PRESENT THEM AS CLICKABLE LINKS, one per line, each labeled with what it shows — e.g. `- [내부 좌석](url)`, `- [외관](url)`, `- [메뉴판](url)`. Use plain markdown LINKS `[label](url)`, NOT image embeds `` (many clients won't inline-render external images and you'd end up hiding them). NEVER tell the user you 'can't display images' — always just post the labeled links so they can tap to view. Only ever show the URLs returned in this `photos` object — they are the owner's verified images of THIS exact venue. Do not substitute images from any other source, which frequently show the WRONG place (e.g. a similarly-named chain) and misrepresent the venue. If `photos` is absent or count=0, tell the user there are no owner-uploaded photos yet — do not fabricate any.

get_place

Check the current status of a reservation ONCE (no waiting), by its reservationId. Status is one of: 'pending' (waiting for the owner), 'confirmed' (owner accepted), 'cancelled' (owner declined), 'expired' (owner didn't respond in time), 'no_show'. For a fresh reservation you're waiting on, prefer wait_for_reservation (it blocks until the owner responds). Use get_reservation for a one-off status check.

get_reservation

List the business_category values available in the oneset with counts (currently restaurant, cafe, bar). Use when the user asks what kinds of places you can find, or to confirm a category before filtering.

list_categories

Find venues near a lat/lng center within radius_m (each result includes distanceM). ORDER: set `sort` — "distance" (default) for a literal closest-first list, "discovery" for a recommendation-quality list within the radius. Use "discovery" whenever the ask is "추천/좋은 곳/괜찮은 데" rather than "가장 가까운 곳"; nearest-first will otherwise put whatever sits a few meters from the center on top even if it has 8 reviews and no recent activity. You need coordinates: when the user names a neighborhood, subway station, or landmark, call resolve_regions first to get the center. NEVER estimate coordinates yourself for a named place or well-known district (명동/강남역/홍대 …) — hand-guessed centers for famous areas are frequently off by 1km+ and skew results to the wrong neighborhood; resolve_regions gives the accurate center. For a plain "places in <district>" search, prefer search_places with region_name (server-resolved) over this tool. If the user only says "near me" or gives no location, ask for a neighborhood, station, or landmark — do NOT guess coordinates. Coverage is expanding across Korea (strongest in Seoul, Gyeonggi and Jeju; more cities like Busan partial), F&B only (restaurant, cafe, bar). Same attribute filters as search_places (positive-signal only), including `open_at` (only venues open at that date/time — last order and breaks applied) and `reservation_channel` ("yumi" = bookable in this chat, "external" = outside link, "phone" = call). TIME & BOOKING WORDING: "그 시간에 영업해요" is confirmed, "자리가 있어요" is NOT — table availability and party-size capacity are unknown until request_reservation or the venue confirms (see search_places RESERVATIONS). LATE MEAL / LAST ORDER: open_at guarantees the venue is OPEN at that time, not that LAST ORDER hasn't passed; for a late time results already lift venues whose last order is CONFIRMED to cover it, and a venue whose last order is UNKNOWN near closing should be flagged as "라스트오더 확인 필요" rather than promised (request contact_hours for per-day last order — see search_places LATE MEAL / LAST ORDER). LOCALS vs REGULARS: repeat_customers/regulars_favorite are 단골/재방문 signals, NOT proof of "현지인이 가는 곳", and there is NO tourist/large-venue exclusion filter — never claim you filtered those out (see search_places LOCALS vs REGULARS). SOFT & AUTO-RELAXED FILTERS: `atmosphere` is a PREFERENCE that only ranks (never zeroes results) and echoes in meta.softenedFilters; and on 0 results the server auto-retries once with weak convenience filters (parking, wifi, …) dropped, returning them in meta.relaxedFilters — when present, say the results matched everything else but not those dropped filters (see search_places SOFT & AUTO-RELAXED FILTERS). If meta.ignoredFilters is present a filter value was not understood, and if meta.ignoredFields is present a requested field name was invalid (that data is NOT in the result) — retry with a valid value/field name or tell the user rather than ignoring it. If you get 0 results, widen radius_m (up to 5000) or drop a filter before giving up. Every result carries `possiblyClosed`; when true the venue has an unconfirmed government closure signal — strongly down-rank it and warn the user to verify it is still open (see search_places CLOSURE RISK). For up-to-date/reliable picks also request quality (`freshnessScore`) or edge (`reputation.recently_active`, `last_verified_days_ago`): low freshness means hours/price may be outdated — say so and softly prefer fresher venues (see search_places FRESHNESS/STALENESS). SOURCE ATTRIBUTION: rating & reviewCount are unlabeled facts and always a matched pair — never attribute them to a platform (no "카카오 평점"/"네이버 리뷰"), present plainly as the venue's own (see search_places SOURCE ATTRIBUTION). INFLUENCER: results may include `influencerFeatures` (present only when a consented ambassador featured the venue); when present you MAY note it was introduced by them (e.g. 이 집은 인스타그래머 @핸들 님이 소개한 곳이기도 해요 — say 유튜버/틱톡커 per platform), and if `contentUrls` (a list of {url, postedAt}) is non-empty, share the first url as a clickable markdown link (소개 영상 보기: [핸들](url)) — the video/photo is what hooks people (a ready-made `influencerContent` line with the link is also attached — post that link verbatim, not just 링크가 있어요); you may mention postedAt (links over ~1 year old are dropped server-side, so only recent posts appear — if empty, still credit the introduction without a link). Use 소개한 곳 ONLY, never 보증/공인 — it is a discovery signal, not a trust basis, and must not override verification/concerns/closure (see search_places INFLUENCER). YUMI PARTNER (reservation kick): results carry `yumiReservable: true` ONLY for Yumi partner venues, bookable right here in this chat via request_reservation — now in results by DEFAULT. When present, PROACTIVELY surface it as you introduce the venue (이 집은 유미 파트너라, 원하시면 이 채팅에서 바로 예약 요청을 보내드릴 수 있어요) to raise booking rate. Say 예약 요청(request), NOT 예약 확정 — owner must accept. Absent = not an in-chat partner (do not invent it). See search_places YUMI PARTNER.

nearby_places

Request a table reservation at a Yumi partner venue (a venue whose detail shows yumiReservable=true). This has a REAL side effect: it creates a pending reservation and immediately pushes a notification to the owner's phone. Only Yumi partners accept in-chat reservations (owner opted in); if the venue is not a partner you'll get reservation_not_available — then DON'T retry: instead tell the user it isn't a Yumi partner, and if it has a bookingUrl/phone point them there (external booking), otherwise say it's walk-in only. Before calling, CONFIRM the details with the user: which venue (use search_places to get its id), date & time, party size, the guest's NAME, and their PHONE NUMBER. ALWAYS collect a phone number (guestPhone is required) — the owner uses it to reach the guest (no-show/changes); this is true for foreign visitors too (enter their own international number). WHERE THE OUTCOME IS SENT — DECIDE BY THE PHONE'S COUNTRY: (a) KOREAN number (010…/+82) → the phone alone is enough; we text the guest (KakaoTalk+SMS). Do NOT ask a Korean guest for an email. (b) NON-Korean number (any other country code, e.g. +1/+81/+44) → we CANNOT text internationally, so the MOMENT you see a non-Korean number, ask for an EMAIL (guestEmail) in the SAME step and send both together — do NOT wait for the API to reject with guest_email_required and then ask again. So the rule is simply: Korean guest = phone only; foreign guest = phone + email (both). IMPORTANT for foreign/email guests: the confirmation email contains a link where they can view AND cancel the reservation themselves (no code needed — just a confirm tap; Korean guests get the same link by text) — so reassure them they can manage or cancel it from that email. The response returns status 'pending' — it is NOT confirmed yet. DO NOT tell the user the booking is done. Tell them the request was sent and you'll wait for the owner (up to ~5 minutes), then CALL wait_for_reservation with the returned reservationId and keep calling it until the status becomes settled (confirmed / cancelled / expired), and only then report the final outcome to the user (confirmed → tell them it's booked; cancelled → owner declined; expired → no response in time, offer alternatives).

request_reservation

Resolve Korean place names to region_code + center lat/lng + placeCount. Handles admin areas (dong/sigungu/sido), ANY subway station (pass the station name in `dong`, e.g. "무악재역"), commercial-district nicknames (홍대·가로수길·경리단길…), and landmarks — department stores / malls / big attractions plus travel gateways: airports & intercity bus terminals (더현대·코엑스·IFC몰·롯데월드·스타필드고양·에버랜드·DDP·제주공항·김포공항·김해공항·동서울터미널; pass in `dong`). Station/nickname/landmark hits come back with center + radiusM but NO region_code (search them via nearby_places). Use this in TWO cases: (1) for nearby_places — to turn a place name into center coordinates; (2) when you specifically need a region_code, center, or venue count. For a plain text search you usually do NOT need this first — pass region_name straight to search_places (it resolves server-side, incl. stations/nicknames, and returns candidates if an admin name is ambiguous). Never invent region codes or coordinates. Homonyms return several candidates; pick using the user's context or ask which one they mean. Romanized/English names also work (e.g. "Gangnam", "Hongdae", "Seoul") — pass them as-is in dong/sigungu/sido; the server maps common ones to the Korean area. For a whole city or province, put the name in `sido` (e.g. "부산", "제주", "경기") so it resolves to the ENTIRE metro/province rather than a same-named neighborhood — e.g. "부산" → 부산광역시, NOT 오산시 부산동. Coverage is expanding across Korea (strongest in Seoul, Gyeonggi and Jeju; other cities partial).

resolve_regions

OPTIONAL peek — you usually do NOT need this. request_live_status already reuses a fresh owner answer by itself (in ONE call), so calling this first just adds a wasted round-trip. Use it ONLY when you want to see if a recent owner-verified answer exists WITHOUT triggering anything (e.g. to show '방금 확인된 정보'). Returns {found:true, status, note, verifiedAt, validUntil, interestedCount} if a fresh owner-verified answer exists, else {found:false}. USE THIS ONLY for time-sensitive things a map/review/policy field CANNOT answer and that change through the day — the core cases: (A) is a specific item in stock right now / did today's fresh ingredient come in / are they sold out today (e.g. '지금 두바이쫀득쿠키 있어요?', '오늘 방어 들어왔어요?', 'kind=item'); (D) how long is the wait right now ('웨이팅 얼마나?', 'kind=wait'); (E) can a party of a KNOWN size get in right now ('10명 바로 돼요?', 'kind=seats' — always with a headcount; if the user didn't give one, ask them first, since '자리 있어요?' alone isn't answerable). Do NOT use it for things already in venue data: opening hours, parking, pet/kids policy, corkage, general menu — answer those from search_places/get_place instead (asking the owner those just annoys them). Give the topic as the bare subject token only, like a keyword (e.g. topic='두바이 쫀득 쿠키', NOT '두바이 쫀득 쿠키 있어요?').

search_live_status