Simplify GPT-Live tool and skill guides

Author: dvsth

fern/gpt-live/configuration.mdx

@@ -346,7 +346,7 @@ Prerequisites are now in the [Quickstart](/gpt-live/quickstart#before-you-start)
 
 ### Create an assistant
 
-See the [Quickstart](/gpt-live/quickstart#create-the-assistant) for a first assistant, and [Build with tools](/gpt-live/tools#step-1-check-availability) for one with tools.
+See the [Quickstart](/gpt-live/quickstart#create-the-assistant) for a first assistant, and [Build with tools](/gpt-live/tools) for connecting tools.
 
 ### Make a test call
 

fern/gpt-live/design.mdx

@@ -7,7 +7,7 @@ slug: gpt-live/design
 
 A GPT-Live assistant keeps listening and speaking while its reasoner looks things up and takes actions. The conversation and the work run side by side, so part of the design is deciding how they fit together: which work to start early, what the conversation can usefully cover while it runs, and how a result rejoins the conversation when it arrives.
 
-This page works through one conversation: a caller booking an appointment with a small service business. The same thinking applies to support, intake, and other calls that mix questions with actions. The example matches the test service in [Build with tools](/gpt-live/tools), so you can try each idea on a real call.
+This page works through one conversation: a caller booking an appointment with a small service business. The same thinking applies to support, intake, and other calls that mix questions with actions. [Build with tools](/gpt-live/tools) covers the tools behind this example.
 
 The dialogues on this page are illustrations of the behavior to design for. GPT-Live generates its own wording, and results vary between calls, so test your prompts on real calls before relying on a pattern.
 
@@ -88,7 +88,7 @@ Start each piece of work as soon as its inputs are known, and use the conversati
 - A time can be chosen only after the open times are known.
 - A booking can be announced only after the booking tool confirms it.
 
-The useful test for any question during a lookup is whether the outstanding work still answers the caller's need after they reply. The test service returns every open time for the requested day and location. So if the caller says "afternoon, ideally after three" while that lookup runs, the result still covers it, and the assistant can filter. If the caller says "Actually, can we do Riverside instead?", the running lookup no longer answers the request, and a new one is needed.
+The useful test for any question during a lookup is whether the outstanding work still answers the caller's need after they reply. In this example, the lookup tool returns every open time for the requested day and location. So if the caller says "afternoon, ideally after three" while that lookup runs, the result still covers it, and the assistant can filter. If the caller says "Actually, can we do Riverside instead?", the running lookup no longer answers the request, and a new one is needed.
 
 That's why the example lookup returns the whole day rather than taking a time-of-day argument. When you design your own tools, return enough to answer the likely follow-up questions without another round trip, as long as the result stays short.
 
@@ -263,15 +263,15 @@ Interrupting the assistant's speech doesn't stop work that's already running. A
 >
 > **Assistant:** On Thursday downtown I have 9 or 1.
 
-The Friday result may still come back. The speaker should recognize it no longer answers the request and use the Thursday one. Your tools can help by including the date and location in every result, as the test service does, so a stale result is easy to spot.
+The Friday result may still come back. The speaker should recognize it no longer answers the request and use the Thursday one. Your tools can help by including the date and location in every result, as the example's tools do, so a stale result is easy to spot.
 
 If the change arrives after an action has completed, the assistant should say so and follow your procedure for changing it:
 
 > **Caller:** Oh wait, can we make that Thursday instead?
 >
 > **Assistant:** Friday at 2:30 is already booked. I can look at Thursday, and if there's a time you like, move it. Shall I check?
 
-The booking exists until your service cancels or changes it. Tell the reasoner how to change a completed action, and have your service enforce it. In the test service, a move is two separate steps: cancel the Friday booking, then book Thursday. So the procedure finds a Thursday time and gets the caller's agreement first, then cancels and books. If the second step fails, the assistant says what actually happened: Friday was cancelled and Thursday wasn't booked.
+The booking exists until your service cancels or changes it. Tell the reasoner how to change a completed action, and have your service enforce it. In this example, a move is two separate steps: cancel the Friday booking, then book Thursday. So the procedure finds a Thursday time and gets the caller's agreement first, then cancels and books. If the second step fails, the assistant says what actually happened: Friday was cancelled and Thursday wasn't booked.
 
 ### Questions and changes of topic
 
@@ -456,7 +456,7 @@ Your service remains responsible for enforcing rules that matter. A prompt that
 
 ### Example: split a scheduling prompt
 
-These are the prompts from the test assistant in [Build with tools](/gpt-live/tools). The speaker prompt follows a structure with labeled policy sections, which makes each decision easy to find and adjust:
+These are the prompts for the appointment assistant used throughout this page. Its tools are described in [Build with tools](/gpt-live/tools). The speaker prompt follows a structure with labeled policy sections, which makes each decision easy to find and adjust:
 
 ```text title="model.speaker.instructions"
 You are the booking assistant for Example Service Studio, a fictional business

fern/gpt-live/migrate.mdx

@@ -269,7 +269,7 @@ Each specialist's procedure becomes a skill's `content`, and its tools become th
 }
 ```
 
-The `toolIds` are the IDs of the saved tools the scheduling assistant used. Tools that several skills need, or that must always be available, go in the assistant's base tools instead. Here `getServiceInfo`, `endCall`, and any transfer to a person are base tools. See [Reasoner skills](/gpt-live/skills) for a complete, downloadable version.
+The `toolIds` are the IDs of the saved tools the scheduling assistant used. Tools that several skills need, or that must always be available, go in the assistant's base tools instead. Here `getServiceInfo`, `endCall`, and any transfer to a person are base tools. See [Reasoner skills](/gpt-live/skills#example-scheduling-and-service-questions) for the full procedure and tool placement.
 
 ### 4. Turn handoff conditions into descriptions and triggers
 

fern/gpt-live/quickstart.mdx

@@ -145,5 +145,5 @@ See [the troubleshooting guide](/gpt-live/testing#said-goodbye-but-the-call-didn
 ## Next steps
 
 - **[Design conversations](/gpt-live/design):** how to shape a conversation that reaches the caller's goal while work runs in the background.
-- **[Build with tools](/gpt-live/tools):** connect a test service and make a real lookup and booking.
+- **[Build with tools](/gpt-live/tools):** connect your service so the assistant can look things up and take actions.
 - **[Migrate to GPT-Live](/gpt-live/migrate):** move an existing assistant or squad.

fern/gpt-live/skills.mdx

@@ -9,7 +9,7 @@ As an assistant takes on more kinds of work, its reasoner prompt fills with proc
 
 A **reasoner skill** groups one procedure with the tools it needs. The reasoner sees a short catalog of skills and loads the ones a request calls for. The caller still hears the same assistant throughout: skills change what the reasoner works with, not who the caller is talking to.
 
-The examples add two skills to the appointment assistant built in [Build with tools](/gpt-live/tools), which checks and books times for a fictional business.
+The examples on this page use an appointment assistant that checks open times, books and cancels appointments, and answers questions about the business.
 
 ## When a skill helps
 
@@ -39,68 +39,40 @@ Loading a skill is an extra reasoning step before the skill's tools can be used.
 
 The speaker also sees the skill names and descriptions, which helps it recognize when to delegate. Write descriptions in terms of the caller's need, keep them short, and leave out anything the caller shouldn't hear. Callers don't need to hear skill names, and the speaker prompt can say so.
 
-## Add two skills to the appointment assistant
-
-Skills live in `model.reasoner.skills`. Each has a `name`, a `description`, the `content` of its procedure, and optional `tools` or `toolIds`.
-
-In this version, `getServiceInfo` and `endCall` stay as base tools. Both skills can use `getServiceInfo`, since scheduling needs today's date from it, and ending the call shouldn't depend on loading a skill. The three booking tools move into the scheduling skill.
-
-The complete configuration is available to download. The excerpt below abbreviates the tool definitions so the structure is easier to see.
-
-<Download src="../static/gpt-live/appointment-assistant-skills.json">
-  <Button intent="primary" rightIcon="download">Download appointment-assistant-skills.json</Button>
-</Download>
-
-```json title="model (excerpt, tool definitions abbreviated)"
-{
-  "reasoner": {
-    "instructions": "You handle work for Example Service Studio, a fictional test business. Work from the latest request in the conversation transcript. Transcripts can contain mistakes and later corrections. Load the skill that fits the request. Return short, plain facts the assistant can say, with no Markdown or lists. Never report an action a tool did not confirm. If an outcome is unclear, say so. Call endCall when the caller asks to end the call or says goodbye.",
-    "skills": [
-      {
-        "name": "schedule-appointment",
-        "description": "Check open times, book a time, or cancel or move a booking made on this call.",
-        "content": "Get today's date from getServiceInfo if you don't know it, and resolve relative dates against it. Call lookupAvailability when you have the service (consultation or standard-visit), the location (downtown or riverside), and a date as YYYY-MM-DD. If a detail is missing, return a short question for the assistant to ask. The lookup returns every open time for that day and location, so filter by time-of-day preference without another lookup. A different service, location, or date needs a new lookup.\n\nA caller choosing a time is a selection, not agreement to book. Call bookAppointment only when the transcript shows that, after the caller chose a time from the latest lookup, the assistant read back the day, time, location, and name and asked whether to book, and the caller then clearly said yes. If that read-back and clear yes aren't in the transcript, don't book. Instead, return the day, time, location, and name for the assistant to read back, and say that it needs the caller's confirmation. Use that time's slotId. If details changed after the lookup, look up again first.\n\nTo move a booking made on this call, first look up the new time and confirm with the caller that they want to move to it. Then cancel the existing booking with cancelAppointment and book the new time. These are two separate steps. If the new booking fails after the cancellation, say that the original booking was cancelled and the new time wasn't booked, and offer to look again. Report the booking ID after a successful booking.",
-        "tools": [
-          { "type": "function", "function": { "name": "lookupAvailability", "...": "same definition as in Build with tools" } },
-          { "type": "function", "function": { "name": "bookAppointment", "...": "same definition as in Build with tools" } },
-          { "type": "function", "function": { "name": "cancelAppointment", "...": "same definition as in Build with tools" } }
-        ]
-      },
-      {
-        "name": "answer-service-questions",
-        "description": "Answer questions about services, how long they take, what to bring, locations, hours, and the change policy.",
-        "content": "Use getServiceInfo and answer only from its result. Give the specific fact the caller asked for, not the whole policy. If the caller asks about fees or exceptions the result doesn't cover, say you don't have that information. If the caller was in the middle of booking, say so in your result so the assistant can return to it."
-      }
-    ]
-  },
-  "tools": [
-    { "type": "function", "function": { "name": "getServiceInfo", "...": "same definition as in Build with tools" } },
-    { "type": "endCall" }
-  ]
-}
-```
+## Example: scheduling and service questions
+
+The appointment assistant has two skills. The scheduling skill's procedure, written as plain instructions:
 
-The downloaded file has the full definitions. Point its tools at your running [test service](/gpt-live/tools#run-the-test-service) and update the assistant from Build with tools:
-
-```bash
-jq --arg host "$TUNNEL_HOST" --arg cred "$CREDENTIAL_ID" '
-  def point: if .type == "function"
-    then .server = {url: ("https://" + $host + "/vapi/tools"), credentialId: $cred}
-    else . end;
-  {model: (.model
-    | .tools |= map(point)
-    | .reasoner.skills |= map(if .tools then .tools |= map(point) else . end))}
-' appointment-assistant-skills.json > skills-model.json
-
-curl --fail-with-body -X PATCH "https://api.vapi.ai/assistant/$ASSISTANT_ID" \
-  -H "Authorization: Bearer $VAPI_PRIVATE_API_KEY" \
-  -H "Content-Type: application/json" \
-  --data-binary @skills-model.json
+```text title="schedule-appointment"
+Get today's date from getServiceInfo if you don't know it, and resolve
+relative dates against it.
+
+Call lookupAvailability when you have the service, location, and date. If a
+detail is missing, return a short question for the assistant to ask. The
+lookup returns every open time for that day and location, so filter by a
+time-of-day preference without another lookup. A different service, location,
+or date needs a new lookup.
+
+A caller choosing a time is a selection, not agreement to book. Call
+bookAppointment only when the assistant has read back the day, time,
+location, and name and the caller has clearly said yes. Otherwise, return
+those details for the assistant to read back and confirm.
+
+To move a booking, look up the new time and confirm it with the caller first.
+Then cancel the existing booking with cancelAppointment and book the new time.
+If the new booking fails after the cancellation, say that the original booking
+was cancelled and the new time wasn't booked.
 ```
 
-To reference saved tools instead of inline definitions, use `toolIds` in the skill.
+The service-questions skill is shorter: use `getServiceInfo`, answer only from its result, give the specific fact the caller asked for, and note if a booking was in progress so the assistant can return to it. It has no tools of its own, but it still earns its place: it holds guidance that only matters for that kind of request.
+
+The tools are placed like this:
 
-The service-questions skill has no tools of its own. It still earns its place: it holds guidance that only matters for that kind of request.
+- `lookupAvailability`, `bookAppointment`, and `cancelAppointment` belong to the scheduling skill, because they only make sense within that procedure.
+- `getServiceInfo` is a base tool, because both skills use it.
+- `endCall` is a base tool, so ending the call never depends on loading a skill.
+
+In the assistant's configuration, skills live in `model.reasoner.skills`. Each skill has a `name`, a `description`, and its procedure as `content`. Attach saved tools by their IDs in `toolIds`, or include inline definitions in `tools`. See [Settings and compatibility](/gpt-live/configuration#reasoner-skills) for the field details and limits.
 
 ## Write descriptions the reasoner can select
 
@@ -130,7 +102,7 @@ Skills organize instructions and tools for the reasoner. Some things stay the sa
 
 - **One assistant.** A skill doesn't create another assistant, hand the call off, or change the voice or model.
 - **No workflow engine.** Loading a skill doesn't track which steps are done, enforce their order, or remember task state between requests. The reasoner works from the conversation and earlier tool results.
-- **No enforcement.** Skills don't prevent duplicate actions, check approvals, or keep one skill's information separate from another's. Your service enforces the rules that matter, as the test service does for bookings.
+- **No enforcement.** Skills don't prevent duplicate actions, check approvals, or keep one skill's information separate from another's. Your service enforces the rules that matter, as described in [Actions that change state](/gpt-live/tools#actions-that-change-state).
 - **One copy per assistant.** Skills are saved with the assistant. Copying an assistant copies its skills, and there's no shared skill library to update across assistants.
 
 ## Create and edit skills
@@ -139,20 +111,7 @@ Skills organize instructions and tools for the reasoner. Some things stay the sa
 
 **Through the API**, set `model.reasoner.skills` when you create or update the assistant. Inline tool definitions in a skill's `tools` are available through the API and assistant JSON.
 
-**From Markdown**, import a file whose frontmatter holds the name and description, with the procedure as the body:
-
-```markdown title="schedule-appointment.md"
----
-name: schedule-appointment
-description: Check open times, book a time, or cancel or move a booking made on this call.
----
-
-Get today's date from getServiceInfo if you don't know it, and resolve
-relative dates against it. Call lookupAvailability when you have the
-service, location, and a date as YYYY-MM-DD...
-```
-
-Other frontmatter fields are ignored, and tools aren't imported. Attach them to the skill after importing.
+**From Markdown**, you can import an existing skill with `name` and `description` in its frontmatter and the procedure in its body. Other frontmatter fields are ignored, and tools aren't imported. Attach them to the skill after importing.
 
 **With Composer**, ask in plain language. Composer can read, create, rename, edit, and remove skills, and attach saved tools, through the assistant's normal draft and publish flow. For example:
 
@@ -164,25 +123,13 @@ Every saved tool a skill references must exist. A missing tool reference stops c
 
 ## Test a detour and return
 
-The case that shows whether skills are working is a request that moves between them. During a booking, ask a service question, then carry on:
-
-> **Caller:** Friday downtown, a consultation. Actually, what if I need to change it later?
->
-> **Assistant:** You can change or cancel up to 24 hours ahead at no charge. Friday downtown I have 10:30, 2:30, or 4.
->
-> **Caller:** 2:30, under Sam Lee.
->
-> **Assistant:** That's Friday at 2:30, downtown, under Sam Lee. Shall I book it?
->
-> **Caller:** Yes.
-
-Check three things together:
+Skills matter most when a call moves between them. Test a caller who asks a service question in the middle of booking, then carries on, and a caller who comes back to a booking that's already been made.
 
-- **The call's messages** show the skill loads and tool calls. You should see the scheduling skill loaded for the lookup and booking, and the service-questions skill, or `getServiceInfo`, for the question.
-- **The service state** shows one booking, for the time the caller confirmed.
-- **The recording** shows the assistant answered the question and returned to the booking without asking for the details again.
+For each, check three things together:
 
-Try a detour after a booking is complete too, and check that the assistant doesn't book again when the caller returns to the topic.
+- **The call's messages** show which skills loaded and which tools ran. The scheduling skill should load for the lookup and booking, and the service-questions skill, or `getServiceInfo`, for the question.
+- **Your service's records** show one booking, for the time the caller confirmed, and no second booking when the caller returns to the topic.
+- **The recording** shows the assistant answered the question and returned to the booking without asking for details again.
 
 ### When skills misbehave