Zooza MCP Server

Writes a class to api-v1 in one shot: creates the schedule, attaches any selected payment templates (bundled inline), and posts the assembled events array. Call this only after the user has confirmed the class shell (from `classes_preview_schedule`) and the full event list (accumulated from one or more `classes_preview_events` calls). For lead-collection classes, pass `events: []`. Returns the created schedule's id and url plus the list of created event ids. If api-v1 silently skips any events (a known quirk), the tool surfaces the mismatch as an error so the caller knows the partial state. `schedule.name` is OPTIONAL — omit unless the user explicitly asked for a custom class name. api-v1 auto-renders `{course_name} {class_name} {session_dates}` end-user-facing when name is absent.

Applies a class edit previously previewed by classes_prepare_update. Only call this after the operator has seen the preview (field changes + how many sessions the cascade touches) and EXPLICITLY confirmed. Takes the `token` from classes_prepare_update — the changes are frozen in the plan and cannot be altered here; to change anything, call classes_prepare_update again. Returns which classes were updated and how many sessions the cascade rewrote.

List the company's billing periods, optionally filtered by name. Returns a slim list of `{id, name, active}`. Active periods only by default; pass `include_inactive: true` to see deactivated ones too. Used by the class-management flow when `classes_preview_schedule` warns about a missing `billing_period_id` — the user picks a period from the returned list. Volume is small (typically <30 per company); the tool fetches all and filters MCP-side. No pagination.

Search this company's CLASSES — the scheduled groups inside a programme (a "class" / "group" / "skupina"; internally a *schedule*) — by name (substring) and resolve them to a `schedule_id`. Reach for this whenever the user names a specific group rather than a whole programme ("the Nejaké class", "the Monday 5pm group", "her Wednesday ballet class"), or whenever a downstream tool needs a `schedule_id` — most importantly `comms_prepare_message` targeting everyone in one class (`audience.schedule_id`). This is the missing middle rung between `classes_find_courses` (finds the PROGRAMME → `course_id`) and `sessions_find_events` (finds individual dated SESSIONS → `event_id`): a class is one recurring group within a programme, made of many sessions. Optionally narrow by `course_id` (classes inside one programme), `trainer_id`, `place_id`, `day` of week, or `registration_type`. Returns a slim list — `{schedule_id, name, course_id, start, end, time, trainer_id, trainer_name, place_id, place_name, capacity, registrations_count, status}` — enough to disambiguate when several classes share a name, never enough to mutate. `course_id` is returned but not the course name (resolve it with `classes_find_courses` if you need it). By default returns active + paused (inactive) classes; pass `include_archived: true` to search archived classes instead. Does NOT create or change classes (that is `classes_preview_schedule` → `classes_commit_class`) and does NOT list a class's sessions (use `sessions_find_events` with the `schedule_id`).

Search the company's courses by name (substring match) and optionally by registration_type / course_type. Returns a slim list of matches — `{id, name, registration_type, target_audience, price, schedules_count, ...}` — enough to disambiguate, not enough to act. Use this whenever the user names a course in natural language; never demand a raw course_id. Archived courses are excluded by default (pass `include_archived: true` to opt in). Pagination defaults to page 0, page_size 25 (max 200); `truncated: true` is returned when more matches exist than the current page reveals. `registration_type` business meanings (when filtering, AND when surfacing results to the user — always translate to these terms, never show the raw enum value): - `single` — drop-in / per-session: customer books one event at a time. - `full2` — full-course enrollment: customer signs up for the entire course/schedule in one go. - `open` — open-ended / membership: no fixed enrollment window; customer joins and stays.

Search the company's venues by name (substring) and/or city. Returns a slim `{id, name, city, street, rooms: [{id, name, capacity}]}` per match. Rooms are inlined because picking a venue is usually followed by picking a room — saves a follow-up call. api-v1 doesn't support server-side filtering on /v1/places, so the MCP fetches up to 1000 places and filters MCP-side; this matches what the app picker does. Pagination defaults to page 0, page_size 25 (max 200).

Returns all valid field values for building class schedules and payment plans in Zooza. No Zooza API call — hardcoded from Events_Preview.php and Payment_Schedule.php. Call this BEFORE classes_preview_schedule or classes_commit_class to avoid validation errors. Critical: weekdays must be 3-letter lowercase (mon/tue/wed...), NOT 'monday' or '1'. Critical: until_date and count are mutually exclusive — sending both causes an API error. Examples: domain="event_generation" → cadences, weekdays, time format; domain="payment_schedule" → schedule types and billing frequencies; empty call → both sections.

Preview an edit to one or more existing classes (a "class"/"timetable" is the recurring group within a programme). Use this to change a class's settings — name, price, registration fee, capacity, billing period, online-registration, status — and/or its instructor, venue, or session duration. Changing instructor/venue/duration forces a `session_scope` choice about existing sessions: "upcoming" (this class + its future sessions — usually what people mean), "all" (every session incl. past), or "class_only" (re-advertise the class but leave existing sessions on their old value — the #1 cause of "I changed it but the sessions still show the old value", so only pick it deliberately). This scope is the OPERATOR's call, not yours: when they haven't stated one, PRESENT the three options and their consequences and let them choose — do NOT silently pick a scope and prepare, and do NOT stall. If the operator asks what a cascade edit will do before committing, explain this same taxonomy (in particular that class_only re-advertises the class but leaves existing sessions unchanged). Returns a preview of exactly what changes and how many sessions are affected — nothing is written until you call classes_commit_update with the returned `token`. Handles one class or many at once. To edit specific individual sessions (move one date, change one session's room), use sessions_update instead. To cancel sessions, use the cancellation tools.

Expands one or more recurrence patterns and/or ad-hoc dates into the concrete list of class sessions, honouring holiday-skip flags. Stateless — performs no writes. Call this once per pattern the user describes during class creation. Accumulate the returned sessions across multiple calls (Claude side) until the user says they're done, then pass the full list to `classes_commit_class`. Each block must carry EXACTLY ONE of `count` (stop after N sessions) or `until_date` (stop on a fixed date) — count mode is preferred when the user says "X sessions". A top-level `to_date` acts as a fallback `until_date` for any block that omits both. `place_id` is required so api-v1 can apply the correct subdivision-scoped school-holiday calendar. When you SHOW the expanded sessions to the user, render them as a weekly GRID (days across the top, time down the left — the Zooza app calendar layout): one representative week with the run range + session count in a caption, NOT a flat date list — unless the user explicitly asks to see every date.

Resolves a new class's *schedule shell* — the course, venue, trainer, capacity, prices, billing period, and default payment templates — and returns the result alongside any warnings. Performs no writes. Use this first in a class-creation flow to confirm the basic class settings with the user before collecting session dates via `classes_preview_events` and committing via `classes_commit_class`. Defaults are copied from the parent course where the caller hasn't specified them (capacity from `target_audience`, prices from the course's pricing fields). Always surface the `warnings[]` array to the user — entries about `online_registration` and `billing_period_id` are real decisions to confirm, not noise. For lead-collection classes (`schedule_type: lead_collection`), the events step is skipped entirely after this preview. `name` is OPTIONAL — do NOT pass it unless the user explicitly asked for a custom class name. End-user-facing display is auto-rendered by api-v1 as `{course_name} {class_name} {session_dates}`, so leaving it blank gives users the most informative label by default. Only set `name` when the user says something like 'call it "Morning Yoga Group A"'.

Write a post-session summary on one event. Two independent fields: - `public_summary` — visible to attendees / parents via their in-app Zooza feed. Use when the user says "write a summary for the parents," "send a recap," "note for the families," etc. After write, every attendee's Person_Feed gets a `SUMMARY_PUBLIC` entry — parents see it in their client portal. - `internal_summary` — admin / team only. Use when the user says "add a note for the team," "private note," "reminder for next week," etc. Not visible to parents. At least one of the two must be provided. Both can be written in one call — the tool fans out the two PUTs api-v1 requires (the upstream endpoint dispatches on which field is in the body, so they cannot be combined). The tool checks the caller's role (**owner / assistant only** — trainers (`member`) cannot write summaries) and the event's `summary_public_locked` flag before writing; refuses cleanly when blocked. Returns the post-write state so you can confirm to the user what's now visible to whom. **Pairs naturally with `sessions_mark_attendance`.** After marking attendance for a session, offer to write a summary (always optional in V1; no api-v1 rule makes it mandatory). Don't volunteer a summary for an event that already has one (`summary.public_set=true` in the sessions_get_attendance / sessions_mark_attendance result) unless the user explicitly asks to update it.

Applies session edits previously previewed by sessions_prepare_update. Only call after the operator has seen the per-session preview and EXPLICITLY confirmed (and, if notify was set, confirmed that clients will be emailed). Takes the `token` from sessions_prepare_update — the edits are frozen in the plan. Returns which sessions were updated and which api-v1 skipped.

List **events** (scheduled sessions of classes) in the caller's company. Use this whenever you need to resolve an `event_id` from natural language ("my next class," "Monday's ballet," "all swim sessions this week," "Sarah's classes tomorrow") before chaining into another tool like `sessions_get_attendance` or `sessions_mark_attendance`. With no filters, returns **ALL upcoming scheduled sessions in the company** (closest first) — not just the caller's. Filters cover date window, course, schedule, trainer, place, room, segment, billing period, status, and event-type (over-capacity, substituted, cancelled, etc.). Each returned row includes denormalised names (trainer, place, event-number), the event's date and duration, `capacity`, `free_spots` (remaining places = capacity − going, or null for open/unlimited events — use this to answer "which sessions still have space"), and an `attendance_counts` object (`going`, `attended`, `noshow`, `canceled`, `canceled_late`, `waitlist`). Read-only — does not modify events. **Critical: "my sessions" / "what am I teaching" / "my classes today".** When the user is asking for THEIR OWN sessions (any first-person framing), you MUST pass `trainer_id` matching `whoami.identity.user_id`. Without it, this tool returns every trainer's events in the company — which is almost never what the user meant when they said "my." The only exception: when the caller's role is `member` or `external_member`, the server silently auto-scopes to their assignments anyway; `meta.scoped_to` in the response flags when this has happened. Filter notes: - `trainer_id` matches across FIVE trainer relationships including pre-substitution and schedule-level extras. Treat it as "events trainer X is connected to," not strictly "events trainer X currently teaches." - `status` uses raw db terms: `scheduled` (default — only state attendance can be tracked on), `unplanned` (includes cancelled events), `finished`, or `any`. - `segment_id=[0]` is a sentinel matching events with NO segment assignment. - Counters in `attendance_counts` may be sub-second-stale; for real-time counts on one event, chain into `sessions_get_attendance`. DISPLAYING A CLASS'S TIMETABLE: when the user wants to SEE a class's sessions (e.g. viewing or COPYING a class), render them as a weekly GRID — days across the top (Mon–Sun), time down the left, like the Zooza app calendar — collapsed to the weekday+time pattern with the run range + session count in a one-line caption; list individual dates only if the user explicitly asks. (Display only — ignore when you are merely resolving an event_id to chain into another tool.)

Read who's enrolled in **one event** (a single session of a class) and their current attendance, so you can show the list and then mark it. Pass an `event_id`; the tool returns each enrolled attendee, their current attendance value (if already marked), and per-row context the LLM needs to mark attendance correctly: `allowed_statuses[]` (the statuses the **current caller** is permitted to set for THIS attendee), `is_trial` / `is_last_trial_session` flags, warnings about cross-company or cascade-sensitive (full2) cases, and — for open-type registrations only — `entrance_voucher` info (how many unused vouchers the attendee has, and whether one is already spent on this event). Use this **before** `sessions_mark_attendance` whenever the user has not already dictated the full list of attendees and marks — typically: "open attendance for X," "who's enrolled in tomorrow's class," "show me Monday's attendance." If the event's course has attendance tracking disabled, the tool returns an `attendance_tracking_disabled` error rather than an empty list. This tool is read-only — it never writes attendance, notes, or summaries. **Talking to the user — vocabulary.** Zooza's customers are activity brands — dance, swim, language, sport, STEAM schools. Call this **"attendance," "the attendance list," "the class list," or "who's coming."** Don't expose the tool name or use sports/HR jargon ("roster") — it reads as foreign to these businesses. When the user asks to "see attendance" / "open the register" / "who's in Monday's class," just call this tool and render the list directly. **Attendee vs client (critical for children's-class programmes).** Each row carries TWO people: - `attendee` — who actually shows up to the session. Often a child (Zooza data-model name: `customer`). May have `user_id: 0` when they aren't a registered account holder, which is normal for children. `attendee.date_of_birth` is available. - `client` — the account holder / payer (Zooza data-model name: `buyer`). Usually the parent. Has a real `user_id`. Contact info (`email`, `phone`) lives on the client when the attendee is a child; copy from client when speaking to / messaging the family. - `display_name` — a pre-formatted one-line label. When attendee == client (adult attending themselves), just the one name. When they differ, `attendee_name (client_name)` — e.g. `"Jozko Jozko (Martin Rapavy)"`. Use this when listing attendees; the LLM doesn't need to compose it from scratch. Response shape notes: - `allowed_statuses[]` already factors in the caller's role, `company.trainer_attendance_management`, and the row's cross-company state. Do not propose a status not in this array — refuse locally and explain instead of calling `sessions_mark_attendance` to discover the constraint. - `is_last_trial_session` is currently `null` in V1 (derivation requires either a new api-v1 field or extra per-row lookups; deferred). Treat `is_trial=true` as the trigger for caution — a future enrichment will tighten this. - `entrance_voucher` is non-null only when `course.registration_type="open"`. Check it before setting `sessions_mark_attendance`'s `use_voucher=true` on a `going` write. - `summary` block at the top level surfaces whether this event already has a public / internal session summary (`public_set` / `internal_set`), whether the public one is locked, and whether the caller's role is permitted to write summaries (`writable_by_caller`). After the user has marked attendance, the LLM can use this to offer `sessions_add_summary` as a follow-up when appropriate.

Record per-attendee attendance for **one event** (a single session of a class — e.g. "Monday Ballet on 2026-06-03 at 09:00"). Pass an `event_id` and a list of attendees, each with their own attendance value (`attended`, `noshow`, `canceled`, `going`, `ignore`). Each value is set on **that one attendee for that one event**, never on the event as a whole. The tool writes each attendee individually and returns a per-row outcome. Use this **after** you already know the event and the attendees you want to mark — typically because the user dictated them or because you previously called `sessions_get_attendance`. If you don't yet know which event or who's enrolled, call `sessions_find_events` or `sessions_get_attendance` first. This tool does **not** cancel or reschedule the event itself or handle trialist follow-ups — those are separate tools. **Follow-up chaining.** The response includes a top-level `summary` block with `public_set` / `internal_set` / `writable_by_caller` flags. After a successful mark, if `summary.public_set=false` AND `summary.writable_by_caller=true`, proactively offer the user the option to write a parent-visible recap via `sessions_add_summary`. If `writable_by_caller=false`, don't offer (the caller's role can't write summaries). If `public_set=true`, don't volunteer an update unless asked. **Trial follow-ups.** A per-row `pending_action: "trial_followup"` (with `todo_id`) means that attendee just completed their trial by being marked `attended` — a follow-up (parent feedback + continuing-class recommendation) is now pending. Tell the user it's waiting and offer to handle it; the attendance skill resolves it against the todo. This tool only surfaces the hint — it does not orchestrate the follow-up. If the field is absent, there's nothing pending. Attendance value semantics: - `attended` — attendee was present. - `noshow` — attendee did not show up and did not warn. - `canceled` — attendee cancelled (admin-recorded). Triggers server-side make-up credit creation automatically when the programme allows it; do not call any other tool to issue credits. - `going` — pre-event RSVP / "planning to attend." Restricted for member/receptionist roles under `trainer_attendance_management="limited"`. - `ignore` — hide this event from the attendee's history (Zooza-specific; rare). `use_voucher` is a tentative V1 design: only meaningful when `attendance="going"` AND `course.registration_type="open"`. Check the attendee's `entrance_voucher.unused_entrance_vouchers > 0` (from `sessions_get_attendance`) before setting it to true; the server silently downgrades to cash debt when no voucher is available.

Preview edits to specific individual sessions (events) of a class — reschedule a session's date/time, or change a hand-picked session's instructor, venue/room, block, or duration. Works on one session or a chosen set (pass their event ids). Returns a per-session before→after preview; nothing is written until you call sessions_commit_update with the returned `token`. Optionally set `notify: true` to email enrolled clients about the change. Use this when the user points at particular sessions ("move next Tuesday's class to Wednesday 5pm", "change the room for the July sessions", "give Friday's session to Jana"). To change an attribute across ALL or all upcoming sessions of a class in one go, use classes_update with session_scope instead. To cancel sessions, use the cancellation tools — this tool does not cancel.

Executes a message plan previously created by comms_prepare_message. Only call this after the operator has seen the plan (recipient count, content) and EXPLICITLY confirmed sending. Takes the `token` from comms_prepare_message — the audience and content are frozen in the plan and cannot be changed here; to change anything, call comms_prepare_message again. Most sends complete in this one call. BUT if the audience is larger than the company's approval threshold, api-v1 creates the job in `pending_approval` and this tool returns `requires_second_confirmation: true` with the recipient count and the job id — and sends NOTHING yet. When that happens: show the operator the exact recipient count and ask a SECOND, explicit confirmation (e.g. "Send to all 105 clients?"). ONLY after they explicitly say yes, call comms_commit_message again with the SAME token and `confirm_large_send: true` to release the send. The operator never has to leave the conversation to approve. If they decline, send nothing. Returns the created message job id and status.

Returns all valid merge variables for Zooza message templates (email, SMS, WhatsApp). Format: *|VARIABLE_NAME|* (MailChimp-compatible). No Zooza API call — hardcoded from Merge_Vars::merge_vars() in api-v1. Use this BEFORE writing any message template to get correct variable names. Claude must not invent variable names — only variables listed here are valid. Examples: category="financial" → payment and balance vars; medium="sms" → SMS-safe vars with HTML warnings; empty call → full catalogue grouped by category.

Lists the automated email templates Zooza sends to this company's clients — registration confirmations, trial follow-ups, cancellation notices, session reminders, loyalty/discount emails, and custom templates. For each template returns its trigger `type`, subject line, and whether the company uses the stock Zooza default or has customized it. Use this to see which automated emails exist, check what has been customized, or look up a template's `type` before previewing or sending it (comms_prepare_message accepts that `type`). This tool only lists email templates — for the merge variables (*|FIRST_NAME|* etc.) usable inside template bodies, use comms_list_merge_vars instead. Read-only; sends nothing. Bodies are full HTML and large — only set include_body when the user asks to see template content.

Plans an email to clients of this company WITHOUT sending anything. Describe the audience (a course/programme, a class schedule, a specific booking, one client, a saved segment, an ad-hoc cohort, or course-level labels) and the content (an existing template `type` from comms_list_templates, or a custom subject + body which may use *|MERGE_VAR|* tags from comms_list_merge_vars). Returns the estimated recipient count, a sample of recipients, the content as it will be sent, warnings (unknown merge tags, zero recipients), and a single-use `token`. Show this plan to the operator and get their explicit confirmation, then call comms_commit_message with the token to actually send. Call comms_prepare_message again with adjusted filters to refine the audience — it is free and repeatable. Resolve names to ids first: classes_find_courses for a course/programme → course_id, classes_find_classes for a class/group by name → schedule_id, sessions_find_events for a single session → event_id; never guess ids. When the operator names an ad-hoc cohort rather than the whole company — "everyone who hasn't paid", the unpaid roster, the waitlist, this week's sign-ups — resolve it with bookings_find and pass the resulting registration_id LIST as audience.registration_id. Reserve audience.whole_company for genuinely company-wide sends; do NOT use it as a shortcut for a named subset, or you email far more people than the operator asked for.

Search the company's team members eligible to be assigned as trainers on classes. Returns a slim `{id, full_name, email, active, virtual}` per match. By default only active team members (owner/member/external_member/assistant/main_member roles) are returned; pass `include_inactive: true` to include former staff. Optional `place_id` / `course_id` filters narrow to trainers associated with a specific venue or course. Used in `class-management` Step 1 to resolve a trainer from the operator's words. **Virtual trainers** are also included in results (always, regardless of place/course filters — they're system-wide placeholders, not tied to any real venue/course). They have `virtual: true`, a synthetic id (>= 9000000000000), and no email. Pick one whenever the operator says any of: 'we'll decide later', 'no trainer yet', 'TBD', 'unassigned', 'guest', 'external speaker', or similar. Three system virtual trainers ship by default: 'To be decided', 'Trainer unassigned', 'Guest trainer'.

List the company's trainer rate types — the named pay rates a trainer can be assigned on a class or session (e.g. "Hourly", "Per class"). Returns a slim list of `{id, name, minutes, type}`, optionally filtered by name. This is the ONLY way to turn a rate the operator names ("the hourly rate", "per-session pay") into the `trainer_rate_type_id` that classes_prepare_update and sessions_prepare_update need — never guess that id. Trainer rate types are company-level configuration (like billing periods and venues), not a per-trainer attribute, so this is a small flat list, typically a handful per company. No pagination.

Find this company's bookings — a client's enrolment in a class (registration; "prihláška"/"Buchung") — and resolve them to a `registration_id`, or a client to a `user_id`. Use for "is X enrolled?", "who's in this class?", "who hasn't paid?" (set `payment_status:["unpaid","partially_paid"]`), and "find client X". Filter by `search` (loose: name/email/phone) or `name`, by `course_id`/`schedule_id` (resolve via classes_find_courses / classes_find_classes), `user_id`, `status`, `payment_status`, or booking date with `created_from`/`created_to` (the "new registrations this week" lever). `distinct:true` returns one row per client (→ `user_id`) for person lookups. Chain a result's `registration_id` or `user_id` straight into comms_prepare_message (`audience.registration_id` / `audience.user_id`). Class/programme NAMES aren't returned — resolve the ids via classes_find_* if you need them. Defaults to active enrolments; guest, waitlist, canceled and deleted are excluded unless you pass `status`. Read-only — does not create or change bookings.

Returns a structured description of Zooza's domain entities — hierarchy, roles, valid field values (enums), parent/child relationships, and disambiguation rules. No Zooza API call is made — purely hardcoded domain knowledge. Call this before any class-creation, booking, or attendance tool to avoid entity confusion. Examples: entity="programme" → registration_type enums; entity="booking" → status values; entity="credit" → make-up / replacement entitlements (the "unused/expired make-ups" and "credits" concept); empty call → full hierarchy with all entities.

Free tool — no Zooza API call, no company_id required. Two modes: "start" → returns the 8-question interview template for Claude to conduct conversationally. "build" → validates answers against the Zooza glossary, returns a TerminologyProfile JSON plus a /remember instruction so Claude saves the profile to memory. Run once per user. The saved profile is auto-loaded in every future Zooza session — no re-configuration needed. Call get_skill('negotiate-terminology') before starting the interview.

Return the REAL, pre-aggregated numbers for ONE business question about an activity brand — and the basis for SHOWING it. This is how you show an operator a report / dashboard / chart of their business numbers (occupancy, unpaid, churn, attendance, trials, retention, revenue, "how are we doing", per programme / venue / instructor): call this, then COMPOSE a focused report as an ARTIFACT in the conversation that renders in the side panel — do NOT hand the user a link or open a browser page. Views: occupancy, unpaid, churn, attendance, trials, retention, clients_by_location, replacements, summary. Use view="replacements" for ANY question about make-up / replacement credits — "unused make-ups", "expiring make-ups", "credits", "náhrady / náhradné hodiny", "are we overloaded on make-ups", make-up demand vs available slots per programme (this IS the credits report; Zooza HAS make-up credits even though they are not in the business_dashboard views). The result has `headline` (computed key figures), `rows` (chart/table-ready, named, capped), `note` (a data-aware caption), `currency`, and `period`. RULES: every number you show the user MUST come from this result verbatim — never invent, estimate, or recompute figures, and never draw a chart without calling this first. Render charts with inline SVG/CSS — no external CDN or chart library (the artifact sandbox blocks them). If a view returns no rows, say so plainly. Follow get_skill("report-compose").

Returns the full markdown playbook for one of the registered skills. Call this BEFORE starting a flow named in the server's instructions — the playbook contains the interview steps, mapping rules, and confirmation pattern for that scenario. Available skills: business-model-validator, class-management, communication, feedback-nudge, negotiate-terminology, report-compose, report-discovery, report-page-new, schedule-optimization.

Submit user feedback about the Zooza MCP integration to the engineering team. Two paths: - 'path: "github"' — returns a prefilled issue-creation URL on the **public** `zooza-dev/zooza-mcp-server` repo. The user opens it in their browser and files the issue themselves (no MCP-side auth). The body MUST be fully anonymized (no user_id, company_id, company name, user email/name, course/class/event names, customer/client identifiers). The server runs a safety-net regex and will reject the call if obvious identifiers (long numbers, emails) remain. - 'path: "internal"' — files an issue on the user's behalf in the **private** `zooza-dev/zooza-mcp` repo, recording their authenticated user_id and company_id so engineering can follow up. Use this for users who don't have GitHub or prefer the private channel. ALWAYS show the user the exact 'title' and 'body' and get explicit affirmative confirmation before calling — once invoked with 'path: "internal"', the issue is filed and cannot be undone from this tool. The 'feedback-nudge' skill (load via `get_skill name=feedback-nudge`) describes when to proactively offer this tool and how to anonymize properly.

Search the Zooza domain glossary. Returns canonical term names, definitions, cross-language synonyms, disambiguation rules, and AI guidance notes. No Zooza API call is made — purely local lookup against the compiled glossary. Use this to resolve ambiguous user input before calling operational tools. Examples: query="hodina" → Session; query="kurz", language="sk" → Programme; category="product-hierarchy" → all hierarchy terms; empty call → full index.

Returns the connected user's identity, the companies they can operate on, regional context, and the session's token state. Call ONCE at the start of every conversation. How to interpret the response: - 'status: "ok"' — authenticated, at least one company available. Pick a 'company_id' from 'companies' for follow-up calls (ask the user if more than one exists). - 'status: "no_companies"' — authenticated but no companies linked. Surface 'status_message' verbatim. No other tool will work. - 'status: "invalid_user"' — account rejected by api-v1. Surface 'status_message' verbatim. - 'status: "api_error"' — api-v1 unreachable. Surface 'status_message' and suggest retry. Identity fields (use these to scope follow-up calls to the calling user): - 'identity.user_id' — the caller's Zooza user id. Pass this as 'trainer_id' to filter sessions_find_events / sessions_get_attendance / etc. to the user's OWN data whenever the user says "my sessions," "my classes today," "what am I teaching tomorrow," etc. Without it, sessions_find_events returns ALL company events, not just the caller's. - 'identity.email', 'identity.name' — for display only. Regional context fields (use these to adapt behaviour): - 'server_region' — which Zooza installation this token routes to, taken from the JWT 'region' claim: "eu" (SK/CZ/DE/RO/HU/IT/PL), "uk", "us", "asia". This is the API-instance region, NOT the company's market region. Null in dev-fallback (no JWT). - 'company.region' — the company's MARKET region code (e.g. "sk", "cz", "de", "en"). Different axis from 'server_region': one EU instance ('server_region: "eu"') serves Slovak, Czech, German, … companies. - 'company.locale' — BCP-47 locale for date/number/currency formatting (e.g. "sk-SK", "cs-CZ", "en-GB"). - 'company.language' — the company's primary language code. - 'company.currency' — the company's currency (e.g. "EUR", "CZK", "GBP"). Use 'company.region' and 'company.language' to resolve terminology: a Slovak company saying "kurz" means Programme; a Czech company saying "lekce" means Session. When region context is available, skip asking the user to clarify language. Branding (per company in 'companies[].branding'): - 'branding.logo' (boolean) and 'branding.primary_color' (#hex or null) report what brand assets were cached for this company. Use 'primary_color' to brand a report artifact you compose for the client; the actual logo image is held server-side and never passes through you. Null branding = fetch failed or nothing configured; default to Zooza styling. Feedback context (used by the 'feedback-nudge' skill): - 'last_feedback_at' — ISO timestamp of the user's last MCP feedback submission, or null if never. Drives the skill's 7-day cool-off on proactive feedback nudges. - 'feedback_count' — total submissions to date (0 if never). Tool-list freshness (Zooza has no marketplace auto-update, so proactively spot an out-of-date connector). There are TWO independent staleness signals — check BOTH: 1. NEW or REMOVED tools — compare 'tool_surface.names' (every tool the live server exposes) against the tools you actually have available in THIS session. Any name in that list you do NOT have = the client is missing newly-added tools. 2. UPDATED tools (same names, changed behaviour) — compare 'server_version' in this response against the [SURFACE_BUILD: …] marker at the very end of THIS tool description. If they differ, the tool DEFINITIONS you currently hold are from an OLDER build even when every tool name still matches — an existing tool's description, inputs, or behaviour changed after the client last connected. (This is why a deploy that only tweaks existing tools is still detectable.) If EITHER signal fires, tell the user once — briefly, not naggingly — that their Zooza tools are out of date, and how to refresh: in Claude Desktop or Claude Code toggle the Zooza connector off then on (or reconnect / reinstall it); a browser client may just need a reload. Do NOT prompt when neither signal fires. Never surface 'sub' or 'scopes' to the user — diagnostic only. [SURFACE_BUILD: 0.3.1]