> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfais.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Setting up your prompts
> Build a prompt library of real buyer questions — the single decision that defines everything Surfais measures.
Prompts are the most important thing you set up in Surfais. Everything else — your AIS Score, visibility percentage, sentiment tracking, competitor comparisons — is computed from how five AI platforms answer the prompts in your library. Get your prompts right and every other number on your dashboard becomes trustworthy. Get them wrong — too few, too generic, too skewed toward your own brand name — and you're optimising against a measurement that doesn't reflect how buyers actually use AI.
This page is the long version. For the short version, the [quickstart](/getting-started/quickstart) and [onboarding walkthrough](/setup/onboarding) cover the basics of getting your first prompts in. Come back here when you're ready to build the library out properly.
## Why prompts are the highest-leverage decision you make
A prompt in Surfais is a single question — the kind a real person asks ChatGPT, Claude, Gemini, Perplexity, or types into Google and sees an AI Overview for. Every prompt you add gets run against every platform and country you've selected, on a schedule, and the results are parsed for whether your brand was mentioned, where it appeared in the answer, what tone it was mentioned in, and which sources the AI cited.
That means your prompt library isn't a settings page you fill in once and forget — it's the definition of what "AI visibility" means for your brand. Prompts that only ask about your own product by name will never tell you whether AI assistants recommend you when a buyer hasn't heard of you yet — for most brands, that's the visibility that actually grows revenue. And prompts that are really keywords ("CRM software") rather than questions ("what's the best CRM for a five-person law firm") won't resemble what a real buyer sees, because that's not how anyone talks to an AI assistant.
Think of the library as the questions you'd want a well-informed friend to be asked about your category: if their answer is good, you get a customer; if it's bad, or they never mention you, you don't.
## What makes a good prompt
The single biggest quality signal is this: **would a real buyer type this into ChatGPT?** Not "would a real buyer search this on Google" — those overlap but aren't identical, because people phrase conversational questions differently from search keywords.
"Best CRM for a small law firm" is a prompt. "CRM software" is a keyword. AI assistants are built for conversation, so keyword-shaped prompts get treated as loose search terms and give you a fuzzy, unrepresentative answer. If you wouldn't say it out loud to a person, it's probably not a good prompt.
Full sentences, the way people actually type when they're in a hurry. "What's the best home security system for a rented flat?" beats "home security system rented flat best". The parser doesn't need keyword density — it needs a genuine answer to a genuine question.
"Best project management tool" is so broad that ten different AI answers could all be "correct" and tell you nothing useful. "Best project management tool for a 10-person creative agency in London" narrows the answer to what your actual ideal customer would ask.
This is the single most common mistake. See the next section — it's important enough to get its own heading.
## Branded vs non-branded prompts
Surfais automatically classifies every prompt in your library as **Branded** or **Non-branded**, and shows the classification as a small badge next to the prompt text on the Prompts page.
* **Branded** — the prompt text mentions your brand name (or a known alias: a trading name, a common misspelling, a parent or subsidiary brand). Example: "Is Surfais good for tracking AI visibility?" A branded prompt tells you how AI assistants talk about you *when someone already knows you exist* — a reputation check on whether you're described accurately and positively once you're already part of the conversation.
* **Non-branded** — the prompt makes no mention of your brand. Example: "What's the best tool for tracking how AI assistants mention my brand?" A non-branded prompt tells you whether AI assistants recommend you to someone who's *never heard of you* — pure category discovery, the demand you don't already own.
The classification is computed per brand, automatically, using a case-insensitive, word-boundary match against your brand's primary name and any aliases configured on [brand aliases](/setup/brand-aliases). You don't tag prompts as branded or non-branded yourself — Surfais works it out from the text every time your library changes.
If your brand name is a common word (say, a brand called "Bright" or "Apex"), mark it as ambiguous in your [brand profile](/setup/brand-profile). That switches classification to a strict mode: only an exact phrase match of your name or a name alias counts — possessive forms and spelling variants no longer match. Be aware of what it doesn't do: a prompt that literally contains the word ("a bright idea") still classifies as branded, because the phrase is present — the toggle tightens matching rather than judging what the sentence is about.
**Why the split matters:** non-branded prompts are the battleground — where AI assistants actively choose which brands to recommend to someone who hasn't picked a side yet, and the visibility that drives new customers rather than just reassuring existing ones. Branded prompts catch a different problem: wrong facts, outdated information, or a competitor being recommended *instead of* you when someone searched for you by name.
A healthy library leans non-branded — mostly category and use-case questions where you're not named, with a smaller set of branded prompts as reputation spot-checks. Skew the other way and your AIS Score looks artificially strong (you tend to show up well when already named in the question) while telling you almost nothing about whether AI assistants bring you new business. The **Branded / Non-branded** filter on the [Prompts page](https://app.surfais.com/prompts) shows this balance at a glance.
## Four ways to add prompts
### 1. AI-suggested prompts
Every brand's Prompts page includes an **AI-suggested prompts** panel. Surfais reads your brand's domain and profile information (tagline, industry, identity and services tags) and generates candidate prompts phrased the way a real buyer would ask them — a mix of "find" ("best X for Y"), "compare" ("X vs Y"), and "decide" ("which X should I get if …") questions. Duplicates of existing prompts are filtered out automatically; nothing is added until you click, and **Regenerate** produces a fresh batch at any time.
This is also the mechanism behind the [onboarding](/setup/onboarding) suggested-prompts step, where you pick your starting library before your first scan — you can return to it later whenever you want more ideas.
### 2. Add a prompt manually
Click **Add Prompt** on the [Prompts page](https://app.surfais.com/prompts) to open the add dialog. You'll set:
Up to 500 characters. Write it as a real question — see [what makes a good prompt](#what-makes-a-good-prompt) above.
At least one is required. This determines which markets the prompt is scanned in — see [Countries & markets](/setup/countries) for how this interacts with your plan's country limit.
All five AI platforms are selected by default (ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews). Untick any you don't want this specific prompt scanned on — most brands leave all five on unless there's a good reason not to.
Type a tag and press Enter or comma to add it. See [tags and presets](#tags-and-tag-presets) below.
Surfais blocks exact duplicates — if the same prompt text is already active for this brand, you'll get an "already tracked" message instead of a second copy.
### 3. Upload prompts by CSV
For building or migrating a large library in one pass, use **Upload CSV** on the Prompts page. The expected format:
```csv theme={null}
text,tags,platforms,countries,active
"Best home security cameras under £200","pricing;comparison","chatgpt;perplexity","GB",true
"Compare Ring vs Arlo","comparison","chatgpt;gemini","GB;US",true
```
* **`text`** (required) — the prompt itself, maximum 500 characters.
* **`tags`** (optional) — semicolon-separated, e.g. `pricing;comparison`.
* **`platforms`** (optional) — semicolon-separated from `chatgpt`, `claude`, `perplexity`, `gemini`, `ai_overviews`. Omit the column, or leave a row blank, and Surfais defaults to all five.
* **`countries`** (optional) — semicolon-separated ISO 2-letter codes (`GB`, `US`, `IE`, and so on). Leave blank and it defaults to `GB`.
* **`active`** (optional) — `true` or `false`. Defaults to `true` (scanned) if omitted.
* Maximum 500 rows per file — anything beyond that is dropped, with a warning that only the first 500 will be imported.
* UTF-8 encoded with a header row.
* Every row is validated before import — a preview shows **valid** and **invalid** counts with a per-row reason for anything invalid (empty text, text over 500 characters, an unrecognised platform code). Invalid rows are skipped; valid rows still import.
* Rows duplicating a prompt already in your library are skipped and reported separately from invalid rows, so the summary distinguishes "already tracked" from genuine errors.
**Download template** on the upload dialog gives you a correctly-formatted starting CSV.
### 4. Track a Coverage Gap as a prompt
If you've connected [Google Search Console](/search-console/connecting-gsc), the [Coverage Gaps](/search-console/coverage-gaps) page surfaces real organic search queries your website already ranks for that you haven't yet tracked as prompts. Select any number of these queries and bulk-track them in one action — Surfais creates a prompt for each, defaulted to your brand's primary market, and starts measuring AI visibility for search demand you've already proven exists. It's a fast way to grow a non-branded library from queries real people are typing, rather than guessing.
## Tags and tag presets
Tags let you organise and filter a growing prompt library — by funnel stage ("pricing", "comparison", "awareness"), by product line, by owner, or any grouping useful to you. Add tags from the **Add Prompt** dialog or inline from any row (click the tags cell to open the tag editor).
Every tag you add is automatically mirrored into your organisation's **tag preset library**, so it appears as a one-click suggestion for you or a teammate next time, rather than being retyped from scratch. Presets are shared across your whole organisation, not per-brand, so a consistent vocabulary builds up as your team adds prompts. Tag matching is case-insensitive, so "Pricing" and "pricing" are treated as the same tag rather than a near-duplicate.
Use the **Tags** filter on the Prompts page to narrow the table to a specific tag, or combine it with the **Status** (active/inactive) and **Branded/Non-branded** filters — active filters show as removable chips above the table so it's always clear what view you're looking at.
## Prompts per country
Every prompt carries its own list of target countries, independent of every other prompt in your library — run some prompts only in your home market and others across two or three, without duplicating the prompt text. Each (prompt × country × platform) combination is scanned and scored separately, so your UK visibility and your US visibility for the same question are tracked as distinct data points, not blended into one.
Surfais defaults a new prompt's country selection to your brand's primary market (set in your [brand profile](/setup/brand-profile)) when that market is trackable — otherwise you'll pick explicitly. See [Countries & markets](/setup/countries) for the full picture, including per-platform geo behaviour and your plan's country limit.
## Plan limits
Every plan caps the total number of prompts in your account. The cap covers your whole prompt library — it's shared across all your brands on multi-brand plans, and paused prompts still count towards it (deleting a prompt is what frees the slot). Caps are enforced at save time: if adding a prompt (manually, by CSV, or via a suggestion) would take your account over its limit, Surfais blocks the insert and tells you to upgrade rather than silently failing.
| Plan | Prompts per account |
| ---------- | ------------------- |
| Trial | 25 |
| Starter | 30 |
| Growth | 80 |
| Scale | 250 |
| Enterprise | Custom |
On an agency plan with Agency Mode enabled, the same rule applies at portfolio scale: one shared prompt budget across every brand you manage — see [Managing brands](/agencies/managing-brands). Some plans also offer a prompt add-on beyond the base allowance; check [Add-ons](/billing/add-ons) or [surfais.com/pricing](https://surfais.com/pricing) for current availability.
CSV uploads and bulk-tracking from Coverage Gaps enforce the same cap — if a batch would push you over the limit, Surfais imports as many rows as fit and reports how many were rejected for capacity, rather than failing the whole batch.
## Changing and removing prompts
Edit a prompt's countries, platforms, and tags at any time from the table — each is an inline popover, and changes save immediately. Toggle **Active/Inactive** if you want to pause a prompt from future scans without deleting it: an inactive prompt is skipped but stays in your library, ready to reactivate later.
Deleting a prompt is permanent. Surfais asks you to confirm, and the confirmation is explicit that deleting a prompt also removes its associated scan history and mentions — there's no way to recover that data afterwards. If you're unsure whether you'll want the history later, pause the prompt instead of deleting it.
## Prompt library patterns
A few shapes worth deliberately including as your library grows, drawn from the mix Surfais itself suggests when generating candidates:
* **Category head terms** — "best \[category] for \[audience]". Broad but still answerable: "best expense management software for a 20-person startup" rather than just "expense management software".
* **Comparison questions** — "X vs Y" or "how does X compare to Y". Where AI assistants make explicit trade-offs, and where showing up favourably against a named competitor is worth the most.
* **Use-case questions** — framed around a job the buyer is trying to get done, not a product category: "how do I track whether AI assistants recommend my brand" is a use-case question; "AI visibility tool" is not.
* **Decision / pick questions** — "which \[category] should I choose if \[constraint]". Often the most revealing prompts in a library, because the answer has to justify a specific pick rather than list options.
* **Reputation checks** — a small number of branded prompts asking directly about your brand, to catch factual drift or a competitor being recommended in your place.
You don't need every pattern for every product line — but a library that's entirely head terms, or entirely comparisons, under-represents how people actually query AI assistants. Use **Regenerate** for a quick gut-check on shapes you might be missing.
## Next steps
Per-platform answers, brand mentions, and scan history for one prompt.
How country targeting works and your plan's market limit.
Track the brands you're compared against in the same answers.
What happens when your prompts run against the five AI platforms.