Koko

Report how far along one of the user's Koko lists or plans is in its background build. send_to_koko returns before the build finishes: geocoding and the ratings/photos pass continue in the background, and this tool reports where that has got to. Returns a staged message (received → locating → enriching → ready) with a step number and the view link; step == total means the build is complete. ALSO the status of an update_koko that answered it was rebuilding: it says while the update is still rebuilding, then that it is in (with any stop that didn't map) or that it failed (nothing changed).

check_koko_status

List the lists and plans in the user's Koko account (title, kind, place count, id).

my_koko

Retrieve ONE of the user's Koko lists or plans as an EDITABLE structure so you can modify it and push it back with update_koko. Get the id from my_koko. Returns JSON in the same shape send_to_koko uses: {job_id, kind, title, region, description, and either `places` (a list) or `days` (a plan — arrays of stops, each with dwell_min; free-time blocks appear as {free_time:true, duration_min, neighborhood}, and a travel leg as the same block tagged transport_mode with its own transport_start/transport_end/transport_note)}. A plan also carries mode/day_start/start_date. A stop that didn't make the schedule rides the trailing day with an `unscheduled_reason` (place closed / hours conflict / ran out of time) — relay that if the user asks about a missing stop. A stop the user has written a side note on carries it as `note` (only their OWN notes come back — a note written by the creator of a list they bought is shown in the app but is not theirs to rewrite). EVERY LOCATED STOP ALSO CARRIES `resolved` — {lat, lng, address, source} — which is WHERE THE PIN ACTUALLY LANDED, not what you asked for. CHECK IT when travel times look wrong: an address in the wrong city or ward is a mis-geocode, not a routing bug, and it is the usual cause of an absurd leg (a Ginza restaurant once resolved 56km away and showed a 3-hour drive). `resolved` is READ-ONLY — send a better `query` to move a pin. A stop with no `resolved` has no pin at all and is not on the map. A PLAN STOP AFTER THE FIRST ONE OF ITS DAY ALSO CARRIES `travel` — {mode, minutes, source, distance_km, walk_minutes, transit_minutes, car_minutes, note} — HOW THE HOP INTO IT IS BEING TRAVELLED, so you can check the routing and not just the pins. `mode` is what the plan shows ('walk' | 'transit' | 'car'), `minutes` is the gap the schedule left for it, and the per-mode minutes are OUR estimates. `source` is "engine" (our guess) or "you" (a transport already set here, which we no longer re-decide). UNLIKE `resolved`, THIS BLOCK IS WRITABLE — see update_koko's `travel`. `transit_minutes: null` means our station index found no rail route between those pins; in greater Tokyo that usually means the index is thin (no geo for JR or any private railway), not that there is no train. Edit the structure, then call update_koko with the FULL new version.

get_koko

Manually re-pull Google ratings/reviews/hours + photos on an EXISTING Koko list or plan. This happens automatically on send_to_koko, so ONLY call it when the user explicitly asks to refresh an existing list. confirm=false estimates the cost; confirm=true spends and starts the refresh in the background (it returns at once; the data lands over a minute or two).

refresh_details

Save what you just made to the user's Koko account — a LIST or a PLAN, decided automatically from the shape. A PLAN has a schedule (stops with times grouped into days) → pass `days`. A LIST is just places in rank order → pass `places`. Pass EXACTLY ONE. region = 'City, Country'. Whenever the plan includes FREE TIME (a break, downtime, 'explore on your own'), encode that stop as a free-time block ({free_time: true, duration_min, neighborhood?}) — never as a place. Any SIDE NOTE the user gives about a particular stop ('Thursdays only', 'book the counter seat') goes in that stop's `note` — it is kept per-stop and shown on the stop itself, and is a different field from `reason`, which is the one-line pitch on the card. Geocoding is free; ratings/photos fill in afterward. Returns a quick ack + a view link.

send_to_koko

Update an EXISTING Koko list or plan — a FULL REPLACE of its contents from the edited structure you got from get_koko. Pass the WHOLE new version, not a diff: stops you omit are removed, new ones are added, and the order/notes/durations you send win. The list's link and id stay the same; unchanged places keep their pins & photos (only new names are geocoded). TO CORRECT A WRONG PIN, send that stop a more specific `query` (exact name + ward/neighbourhood + city + country): a query that differs from the one the stop was resolved with re-geocodes it, and the old pin is kept only if nothing better is found. Changing `name` or `reason` does NOT move a pin. Drop the `resolved` block or send it back untouched — it is ignored either way. Pass `places` for a list or `days` for a plan (match the kind from get_koko). Keep free-time blocks as {free_time: true, duration_min, neighborhood?} stops — and a JOURNEY (a flight, a train leg) as the one get_koko gave you, transport_mode and its transport_start/transport_end/transport_note intact: drop those and the leg comes back as anonymous downtime. KEEP EACH STOP'S `note` — this call re-creates every stop, so a note you drop from the payload is deleted from the list. Send back the `note` get_koko gave you (edited if the user asked), and add one to any stop they just told you something about. title/region/description/start_date/day_start are optional — omitted ones keep their current values. A plan stop can carry `travel` — the transport into it from the stop before. SEND IT WHENEVER YOU KNOW BETTER THAN A HEURISTIC: our estimate has no timetable and no geo for JR or any private railway, so it mis-routes real journeys and will sometimes choose a car over an obvious train. A `travel` you send is used as given and survives every later edit; get_koko marks those legs `source: "you"`. The expected input is the structure get_koko returns for this job_id with the edits applied, so that the replacement is built from the current version. ATOMIC, AND ASYNCHRONOUS WHEN BIG: the payload is validated first (an error changes nothing), and the new version is built off to the side and swapped in whole. A rebuild that takes more than ~20 s (a long trip, many new places) answers that it is still rebuilding: poll check_koko_status with this job_id until it says the update is in, and send nothing else to this job meanwhile.

update_koko

Identify the authenticated Koko account: returns JSON with username (stable), email, name, username, is_operator, auto_publish_as and creator_handle. No arguments. Call it to confirm which account this connection acts on — e.g. before a send, or when the user asks who they are logged in as. koko_account is the same information as prose.

whoami

Who the connected Koko account is: display name, username, email, whether it is an operator account, the creator storefront it publishes to (if any), how many lists and plans it holds, and — critically — whether sends AUTO-PUBLISH to the public Discover shelf. Call this when the user asks who they are logged in as, when a send is about to go somewhere public, or when anything about the account is ambiguous. Returns only the caller's own account.

koko_account