Screen context
Tell ShowPilot and your agent what each captured screen shows, so tours are written accurately and your agent presents every screen with the right facts.
Your agent can only talk about a screen as well as it understands it. Every capture carries a short screen context: a name, a description of what's on the screen and the state the product is in. ShowPilot writes it automatically when you capture, the writing pass reads it when it drafts a tour, and your agent reads it live while presenting. A minute spent correcting it pays off in every tour and every conversation that uses the screen.
You're in the right place when a tour's copy gets a screen wrong, when your agent describes a screen inaccurately, or when you want to check what the agent knows before a tour goes live.
What is screen context?
Screen context is the description attached to a capture in your library. It has three parts you can edit:
| Field | What to put there |
|---|---|
| Name | A short name for the screen, such as "Payment runs list". It's the name you see in the library, the storyboard and the plan. |
| What's on this screen | One or two sentences the agent reads when it presents this screen. Say what the viewer is looking at and why it matters, in plain words. |
| App state | The state the product is in on this screen, such as "two runs pending approval" or "report filtered to last quarter". |
Behind those fields, ShowPilot also keeps the regions it found on the screen: the navigation, headings, buttons, tables and charts, with their positions. You can see them in the editor but not change them.
ShowPilot writes all of this when a capture lands. The short summary you see on each card under Tours → Captures is the What's on this screen text.
Why does it matter for agent-led tours?
When your agent presents a tour, it doesn't see pixels. It reads the step you wrote for the screen, plus the screen context of the capture behind it. That context is how it:
- Describes the screen accurately. When a visitor asks "what am I looking at?", the agent answers from What's on this screen and App state.
- Finds the right screen to show. When a visitor asks about something the current tour doesn't cover, the agent searches the screens in the hub by their context and can jump to the one that answers the question.
- Stays consistent. The same context serves every tour built from the capture, so the agent tells the same story about the screen wherever it appears.
The writing pass also reads screen context when it plans a tour and drafts the copy. A clear description means better step titles and a better story on the first draft. See Let your agent present a tour.
Where do you open the screen context editor?
There are two ways in. Both open the same editor on the same library capture.
| From | How |
|---|---|
| A hub's Captures tab | Open the hub, select Captures, then select any capture card. Cards show Edit context when you hover. A card with nothing written yet says "No context yet". |
| The builder's storyboard | Open a tour in the builder, hover a screen's thumbnail in the storyboard on the left, and select Edit context. |
Edit context doesn't appear on slides, because slides are written in the builder and have no capture behind them. It also doesn't appear on a screen whose capture was deleted from the library: the tour keeps playing its own copy, but there's no context left to edit. If the builder hasn't refreshed since the delete, the button can still show; selecting it tells you the capture is no longer in the library.
How do you edit a screen's context?
Open the editor
Open Edit context from a hub's Captures tab or from the builder's storyboard. The editor fills the window, titled Screen context: the capture on the left, the fields on the right.
Look closely at the screen
The capture opens fitted to the window. To read small text:
- Select the screen, or select Actual size, to see it at full size. Drag to move around it.
- Select the screen again, or Fit screen, to fit it back in the window.
Video captures play in the editor, so you can check the moment you're describing.
Check the regions the agent sees
If ShowPilot found regions on the screen, a button such as 14 regions the agent sees appears at the top. Select it to draw each region on the screen with its label. Hover a label to see what ShowPilot noted about that region.
- A region with a solid border came from the page itself when you captured it, so its position is exact.
- A region with a dashed border and a ≈ mark was found by looking at the image, so its position is approximate.
Correct the fields
Edit Name, What's on this screen and App state. Write for a listener: the agent reads these while it talks, so plain sentences work best.
To have ShowPilot look at the screen again and redraft the description and app state, select Autofill with AI. It shows "Looking at the screen…" while it works. It replaces What's on this screen and App state, and you can edit the result.
Let it save, then close
Changes save a moment after you stop typing. The corner shows Saving…, then Saved. Select Done to close.
What makes good screen context?
| Do | Avoid |
|---|---|
| Say what the viewer sees and what it's for: "The payment runs list, where finance approves each batch before it's sent." | Restating the page title: "Payments page." |
| Put the specific state in App state: "two runs pending approval, one flagged". | Leaving state in the description, where it's harder for the agent to use on its own. |
| Use your product's own names for things, the way your team says them to buyers. | Internal jargon a buyer wouldn't know. |
| Keep it to one or two sentences. | Long paragraphs. The agent has to say this out loud. |
| Describe the sample data as sample data if that matters, such as "a sample account". | Claims about the viewer's own account. |
Where do your changes show up?
The editor always edits the capture in your library, never a single tour's copy. So a change reaches:
- Every tour built from the capture. The next time your agent presents any of them, it reads the new context. You don't need to publish the tours again for the agent to use it.
- The Captures library. The card summary updates straight away.
- Future writing passes. Plans and copy drafted from now on use the new description. Copy that was already written stays as it is until you rewrite it.
The step text in a tour is separate. To change what a tooltip says, edit the step in the builder. See Step settings.
Test it
Your screen context is working when:
- You open a tour in the builder, hover a screen in the storyboard and select Edit context.
- You change What's on this screen and wait for Saved.
- You open the hub's Captures tab, and the same capture's card shows your new text.
- If the tour is agent-led, you open its link, ask the agent what you're looking at on that screen, and it answers from your new description.
Troubleshooting
| Issue | What to check |
|---|---|
| Edit context doesn't appear on a screen | The screen is a slide, or its capture was deleted from the library. Slides have no screen context. For a deleted capture, replace the screen's capture in the builder to get context back. |
| The agent still uses the old description | Check the editor showed Saved before you closed it. Then check the tour's screen still uses this capture: if someone replaced the capture in the builder, edit the new one instead. |
| Autofill with AI wrote something wrong | Edit the fields by hand. Your edits save over the autofill. |
| No regions button appears | ShowPilot didn't find regions on this capture, which can happen with uploaded images. The description and app state still work. |
| A capture's card says "No context yet" | ShowPilot hasn't written a description for it yet. Open it and select Autofill with AI, or write one. |
FAQ
Does editing screen context change one tour or all of them?
All of them. The editor changes the capture in your library, and every tour built from it reads that capture's context.
Do I need to publish again after changing screen context?
No. Your agent reads screen context live while it presents. Publish only when you change the tour itself, such as its steps or screens.
Is screen context shown to viewers?
Not directly. It isn't printed on the tour. Your agent uses it to understand the screen and phrases its answers in its own words.
Can I edit screen context from the Captures library?
Open it from a hub's Captures tab or from the builder's storyboard. A collection's own page doesn't open the editor.
What's the difference between screen context and hub context?
Screen context describes one screen. Hub context describes the whole hub: what it covers, who it's for and what the agent should never say. See Give ShowPilot context for your tours.