CineOS

Use this to understand the current CineOS AI capabilities, active title examples, supported territories, and booking/truth-state rules. Call this first if unsure what CineOS can currently answer.

get_capabilities

Returns a curated, ranked, genre-diverse shortlist of UK films for open-ended requests where the user hasn't named one specific title: what's on, what to watch, what's playing near them, new releases, the upcoming slate, a weekend family pick, a date-night idea, or films matching a genre, actor, mood or occasion ('rainy day with the kids', 'proper rom-com', 'arthouse date'). Covers the whole UK catalogue — films now showing (with live showtimes) and ones coming soon (with release dates). Set `listing` to the user's intent: 'now_showing' for what's on screen right now ('what's playing this week', 'showing near me tonight'); 'new_releases' for films newly out or opening this week ('new films this week', 'just released'); 'coming_soon' for a future slate ('what's coming in September', 'the autumn line-up'), passing `date_from`/`date_to` spanning the period (e.g. September → 2026-09-01, 2026-09-30). Omit `listing` for a general 'what should I watch' — CineOS then returns a blend of the biggest current releases plus films opening soon. If the user's wording is genuinely unclear between films showing now and brand-new releases, ask one brief clarifying question before calling. Results are curated and ranked (biggest releases and campaign titles first), not an exhaustive list; present them conversationally grouped by who each suits, and offer to narrow by genre/actor/mood/date/location. Returns only verified CineOS data and does not invent films or showtimes. For one named film use get_film_experience; for exact times/cinemas use get_showtimes.

discover_films

Returns CineOS's record for a single named UK film: official trailer, poster, genres, synopsis, cast and crew, BBFC rating, and a booking CTA, plus the user's nearest showtimes when their location is known. Use it when the user names a film and wants details about it — information, trailer, poster, cast, director, release date, or a general 'tell me about X'. Covers the whole UK catalogue including upcoming and not-yet-showing titles, so for a film with no showtimes yet it returns a release-status answer rather than an empty result. Returns only verified CineOS data and does not invent showtimes or booking links. Pass the film title as `q` (e.g. 'The Odyssey'), or its `slug` if known. ALWAYS pass `location` (and `date` if given) when the user has already mentioned where or when — e.g. after a showtimes request for London, call this with location='London' rather than asking again. For full listings, cinemas, and booking use get_showtimes. The card's trailer plays inline, so don't also post a separate trailer link in the text reply.

get_film_experience

Looks up films by title across the UK CineOS catalogue (every synced release, whether or not it's currently showing) — use when the user gives a partial or approximate title or wants a few candidates to choose from. Covers upcoming and not-yet-showing titles as well as current ones, and does not invent matches. For a single named film prefer get_film_experience (richer card); for a broad 'what's on' request use discover_films.

search_films

Use this only after the user has chosen a verified CineOS showtime and wants to book. Returns the branded CineOS handoff link that tracks attribution before redirecting to the cinema.

create_booking_handoff

Use this when the user asks for things to do, weekend plans, rainy day activities, family activities, date night ideas, indoor entertainment, or local cultural activities where cinema could be relevant. Suggests cinema only when a verified CineOS film genuinely fits; never invents films, cinemas, or activities.

discover_cinema_activity

Use this when the user asks for dates, cinemas, times, formats, locations, or currently verified booking options for a film. Returns only verified showtimes with branded booking handoff links. If it returns no verified showtimes, tell the user that plainly — NEVER supplement, backfill, or reconstruct times, cinemas, or booking links from your own knowledge, earlier turns, or the web; presenting unverified showtimes as CineOS data is prohibited and defeats the point of CineOS.

get_showtimes