Tool, group, or journey?
Three shapes for three different problems. Pick the wrong one and the agent gets more surface than it can use.
The surface an agent uses well is small and intent-shaped. When you add a capability, it takes one of three shapes. This page is how to tell which.
The short answer
| The problem | The shape | What it looks like |
|---|---|---|
| One action, one call | A tool | cancel-order, search-products |
| One action the API split into two calls | A grouped tool | upload-media wrapping request-upload and complete-upload |
| A goal that takes several calls, shares state, and ends in one write | A journey | book-ride: resolve, schedule, confirm |
A tool
Most things are a tool. If an agent can express the whole action as one call with the inputs it already has, you are done. The generator makes these from your spec, and reads work immediately.
The question to ask is not "does this endpoint exist" but "would a helpful person do this in one step". If yes, it is a tool.
Grouping
Some endpoints only make sense together. Requesting an upload and completing it are one action that the API happens to split in two calls. An agent should never have to orchestrate that handshake, so the generator detects the pair and emits one coarse, withheld tool next to the members.
You do not usually decide this. Grouping happens at generate time from the spec, merges only when the rules are exact, and skips anything fuzzy with a note. You adopt the proposal by enabling it.
A journey
Reach for a journey when all of these are true:
- The goal takes more than one call. Resolve a destination, then set a time, then request the ride.
- The steps share state. A later step or the submit needs what an earlier step produced.
- At least one input cannot be invented. The ride needs coordinates, which only the geocoder can provide. An agent that guesses gets rejected.
- The end is a real write that a person should confirm.
If a goal has the first two but not the last, you may still want a journey: it is how you keep a multi-call flow from becoming several loose tools the agent has to sequence itself.
The journeys page is the walkthrough.
Signs it should not be a journey
- One call. That is a tool. A one-step journey is a tool with extra steps.
- No shared state. If each step is independent, the agent can just call the tools. Wrapping them adds surface without adding safety.
- More than five steps. Past five, you are usually describing two journeys.
- It is really about navigation. Moving the page around is app behavior, not a tool call. Keep it in your UI.
Signs it should not be a tool
- The name mirrors the route.
post-v1-trips-id-cancelis an endpoint wearing a name. The intent iscancel-trip. - It only makes sense inside a flow. If calling it alone leaves the app in a broken state, it belongs to a journey, not the public surface.
- Two tools are really one decision. If an agent always calls them together, they are one tool.
Next
After you generate
The tools exist. Now decide what agents may actually do, check it, ship journeys for the real goals, and keep it honest as your API changes.
Journeys
A few steps that share state, ending in one write a person confirms. Journeys are how you describe a goal that takes more than one tool call.