GoStudent Tutor Finder

View saved version →

---
name: find-online-tutor
description: Finds GoStudent online tutors who are free at the time the user wants and books the 30-minute trial lesson or a callback from a GoStudent tutoring expert. Use when someone looks for online tutoring or a private tutor for their child or themselves, e.g. "Mathe-Nachhilfe für meine Tochter, 7. Klasse Gymnasium", "online English tutor for GCSE on Tuesday at 5pm", "who can help my son with chemistry on weekends", "profesora de inglés para la ESO", or wants to talk to GoStudent about tutoring.
---

# Find an online tutor and book a trial lesson

The GoStudent Tutor Finder connector (`find_tutors`, `get_tutor`, `book_trial_lesson`, `request_callback`) reads tutors' real calendars and books through the same process as gostudent.org. This skill sets the conversation flow around those tools. Each tool's own description and parameter schema stay authoritative for arguments.

## Scope

Use the tools for: finding 1-to-1 online tutors for a school subject, showing their free times, booking the free trial lesson, requesting a callback.

Do not use them for:
- explaining a topic or helping with homework (answer directly instead);
- in-person tutoring at someone's home;
- prices, packages or contracts. Never invent prices; point to gostudent.org or offer the callback, where a GoStudent expert explains them;
- becoming a GoStudent tutor.

## 1. Understand the need with as few questions as possible

A search needs a **subject**. **School type and grade** make the results and the booking correct. Ask for them at most once, together, and only if they are missing. Proceed without them if the user prefers.

- **Market:** use the user's country (Vienna → `de-at`, Zürich → `de-ch`, Munich → `de-de`). If the country is unknown, infer it from the conversation language. For the school-type names each market uses, see `references/markets.md`.
- **Time wish:** translate it exactly as the `find_tutors` description says:
  - exact time → `dates` + `exact_time`;
  - part of day → `dates` + `time_from`/`time_to`;
  - recurring → `weekdays` + range;
  - no preference → leave empty.
- **Dates:** resolve relative dates ("next Tuesday") to `YYYY-MM-DD` in the market's time zone. Trial lessons start tomorrow at the earliest. If the user asks for today, say so and search from tomorrow.
- **Filters:** set `tutor_gender`, `teaching_language` or `special_need` only when the user asks for them.

## 2. Show results

Call `find_tutors`.

**Hosts that render the interactive cards** (e.g. ChatGPT, Claude):
- Do not repeat every card in text.
- Add one or two sentences: how many tutors fit, and whether the exact time was free or the search was widened.
- Point out a standout fit if there is one, e.g. "Anna has the 16:00 slot and 9 years of experience".

**Hosts without the cards** (e.g. a terminal), show a compact list per tutor:
- name;
- rating with review count;
- one line of experience;
- the three free times as local times.

Never invent tutors, ratings or times. Only show what the tool returned.

## 3. Refine in conversation

When the user narrows down ("a female tutor", "who speaks Turkish", "later in the evening") or asks for "others", call `find_tutors` again:
- keep **all** earlier filters;
- add the new one;
- for "others", pass the already-shown IDs in `exclude_tutor_ids`.

Use `get_tutor` when the user asks about one tutor or wants more times from them.

## 4. Book the trial lesson

The interactive card's booking form handles consent and submission itself. Use the chat path only when the user books by message.

1. **Confirm tutor and time.** Name the tutor and the local time back to the user. Use the slot `start` exactly as returned.
2. **Collect contact details.** Ask for name, mobile number and email, and nothing else.
3. **Check who books.**
   - Booking for a child: `booking_for: "child"`.
   - Learners aged 16+ booking for themselves: `booking_for: "self"`.
   - If the learner is under 16, ask for a parent to book.
4. **Get consent.** Show the consent sentence and privacy link from the `consent` field of the `find_tutors` result verbatim. Ask for an explicit yes. Only then set `consent_confirmed: true`.
5. **Marketing opt-in.** Set `marketing_opt_in: true` only if the user explicitly asks for news from GoStudent. Otherwise leave it false.
6. **Idempotency.** Create one `idempotency_key` (a UUID) per booking attempt. Reuse the same key if you have to call again for that attempt.

Handle the result:

| `status` | What to tell the user |
|---|---|
| `booked` | Booked, with date and local time. Confirmation and lesson link arrive by email from GoStudent. |
| `simulated` | Test mode: nothing was sent. Say so plainly. |
| `pending` | The booking is being processed and a confirmation email follows. **Do not** book again. |
| `slot_taken` | The time was just taken. Offer the returned `alternatives` or call `get_tutor`. |
| `invalid` | Fix the named fields with the user, then call again with the same key. |
| `error` + `booking_failed_callback_created` | The slot could not be booked, but a GoStudent expert will call back to find a time. |
| `error`, other | Booking did not go through. Offer the callback or gostudent.org. |

## 5. Callback from a tutoring expert

Offer `request_callback` when the user:
- wants advice first;
- asks about prices or packages;
- is unsure which subject or format fits;
- does not want to pick a tutor.

Collect the same three contact details. Show the same consent sentence before calling.

- **Preferred time:** pass `date` and `hour` (local, 8–21) if the user gives one.
- **Callback date:** must not be in the past or on a Sunday.
- **Note:** put a short summary of the need into `note`, e.g. "Maths, 8th grade Gymnasium, exam in November". Never put contact details there.

## Privacy rules

- Ask only for the data the booking needs.
- Do not repeat full phone numbers or emails back unnecessarily.
- Never pass contact details to any tool other than `book_trial_lesson` or `request_callback`.

Referenced files: 1 — file references are metadata, not package contents.