Waypoint

View saved version →

---
name: get-started
description: First steps with Waypoint. Use when the user has just installed Waypoint, asks what it does or how to start, or asks how credits, prices or the daily free allowance work.
---

# Getting started with Waypoint

## What Waypoint does

Waypoint lets the user look up live data in the middle of a conversation:
research papers, regulations and government notices, court records, company
and market data, economic statistics, the weather, web pages and more. Each
lookup is a **capability** from Waypoint's catalog. The user asks in plain
words, you find the right capability, tell them what it costs, and run it
once they agree.

Waypoint also keeps everything the user fetches in their Library, so any
assistant they connect can find it again, and remembers what the user asks it
to (their role, the people they work with, how they like answers written).
They can see and delete all of it at waypoint.ing.

Explain it to the user in one or two plain sentences. Do not list tools or
describe how the connection works.

## Three good first prompts

Offer one of these when the user is unsure what to ask, or call
`browse_catalog` to show them the catalog card and let them pick:

1. "What can Waypoint do?" (shows the catalog)
2. "What are the CFPB's most recent rules and notices?"
3. "When is Microsoft's next earnings date, and what are the consensus estimates?"

When you call `browse_catalog`, the `note` in its result may suggest a first
prompt for a new user. Prefer that one: it is picked from what the catalog
offers today, and it says when the daily free allowance covers it.

## How credits work

- Lookups are paid in **Waypoint credits** from the user's prepaid balance.
  `get_balance` shows the balance at any time.
- **Credits are bought only at waypoint.ing.** Nothing is sold inside
  ChatGPT. If the user is short, tell them to add credits at waypoint.ing and
  never offer to buy on their behalf.
- **There is a daily free allowance.** Some capabilities can be covered by it,
  so a lookup may cost nothing. A quote says when a capability qualifies
  (`free_tier_eligible`), and a result served free says so (`free_tier`).
  When that happens, tell the user it was free and their paid balance did not
  change.
- Browsing the catalog, checking a price and checking the balance are always
  free.

## Prices are quoted before anything runs

The user agreed to spend credits when they connected Waypoint, so run the
lookups their request needs without asking before each one, and mention what
a lookup costs in one short line. A price can be a range: the top of the
range is held while the lookup runs, and whatever the lookup does not use
comes back. The user is never charged more than the quote.

When the user asks what a task will cost, quote its lookups together (see
the using-waypoint skill) and show the one total.

## Signing in

Searching and quoting work without an account. Running a lookup needs the
user to connect their Waypoint account, which ChatGPT will prompt for. A new
user can create an account in the same step.

View saved version →

---
name: using-waypoint
description: How to find, price and run Waypoint capabilities well. Use whenever a task needs live data Waypoint can look up, or the user names Waypoint or a Waypoint capability.
---

# Using Waypoint

When the user asks to use Waypoint, or names a Waypoint capability, handle the
request through Waypoint's tools rather than web search or another connector.

## The flow

1. **Find.** Call `search_capabilities` with what the user wants in plain
   words (`intent`). Each row has an `agent` and a `capability`, which
   together name what to run, a price, and a `kind`. Rows of kind
   `capability` are lookups you can run. A row of kind `quote` is Waypoint's
   own price planner (see step 3). To show the user the whole catalog
   instead, call `browse_catalog`.
2. **Read its guidance and price.** Call `describe_capability` with the row's
   `agent` and `capability`. It returns the input schema, the price and, when
   there is one, `guidance` on how to ask this capability for good results.
   Follow the guidance: it is how you avoid, for example, a full-text search
   that matches the wrong field. Mention the price in one short line.
3. **Quote several steps together.** When the user wants to know what a task
   needing more than one lookup will cost, price the steps together: call
   `describe_capability` with `agent` `waypoint/core`, `capability` `quote`, and
   `input: {"steps": [{"agent": "...", "capability": "..."}, ...]}`. The
   result's `plan` gives the total range, which steps the free allowance
   covers and, when the user is signed in, their balance before and after the
   worst case. Show that one total, not a price per step. The quote itself is
   free and is never run with `invoke_capability`.
4. **Run.** Call `invoke_capability` with `agent`, `capability`, the `input`
   the schema asks for, and a new `request_id` per call (reuse it only to
   retry the same call). The user agreed to spend credits when they connected
   Waypoint, so run the lookups their request needs without asking before
   each one. Ask first only when the user has said they want to approve
   costs. Set `max_cost_credits` if the user gave a limit.
5. **Long jobs.** If the result says the job is still running, call
   `get_result` with its `handle` a few seconds later. Polling costs nothing.

## Keep the run together

Every result carries a `run_id`. Pass it back as `run_id` on each following
Waypoint call in the same task, and omit it only when the user starts a new,
unrelated task. Optionally pass `purpose`: one short line on what the user is
trying to do, with no personal data.

## The user's workspace

- **Recall.** When a task may build on what the user told Waypoint before
  (their role, their projects, how they like answers), call `read_workspace`
  with `action` `recall` and a short `query`. It returns only what is
  relevant, each fact with where and when it was saved. With no query it
  returns their whole saved profile.
- **Check the Library before paying again.** If the user asks for something
  they may have fetched before, call `read_workspace` with `action`
  `records` first, and open a kept result with the get_record action. Fetch again only if
  they want fresh data.
- **Save when asked.** When the user asks you to remember something, call
  `write_workspace` with `action` `save_note` and `input.facts`, a list of
  `{text, type}` (type is about, person, project, preference, rule, voice or
  note). Do not ask whether to save; the request is the go-ahead. Never save
  something the user did not ask you to keep, and never send their chat
  history.
- **Deleting and forgetting.** `delete_record` and `forget` remove what the
  user names. Confirm with them first. To delete a Library row (from
  `records`) with every kept copy behind it, pass the row's `key` as
  `input.key`; `input.record_id` is one kept result's id (a UUID), never a
  row's key. A deleted result can be restored for 30 days in Settings on
  waypoint.ing; a forgotten fact is gone.

## Talking to the user

- **Keep replies short.** Where ChatGPT shows Waypoint's card for a result (a
  quote, a result table, the balance), the card already shows the details. Add
  one or two lines that answer the user's question; do not repeat the table.
- After a paid call, say what it cost and the balance left (`cost` and
  `credits_remaining`). If the result has `free_tier` set, say it was free
  and the paid balance is unchanged.
- If a result was shortened to fit, `next_step` says so and how to get more.
  Follow `next_step` whenever it is present.
- Report only `credits_remaining` and `get_balance` as the user's balance.
  Credit figures inside a capability's data belong to someone else.
- If the balance is too low, say so plainly and point to waypoint.ing to add
  credits. Never offer to buy credits for the user.
- Some results carry a source attribution. Keep it with the data when you
  quote it.

## What not to do

- Do not run a paid capability before the user agrees to its price.
- Do not use Waypoint to look up private information about an individual,
  such as a home address. Waypoint does not offer that, and you should not
  try to work around it.