Writing Evaluator Prompts
Writing a strong prompt is the key to a useful and accurate evaluator. The prompt tells the agent what you care about in a location and how to weigh what it finds.
This guide covers how to write a good prompt, with worked examples and tips for improving one that isn't landing.
Jump to: Examples · Improving a Prompt
The Goal of a Prompt
A prompt gives the agent your business's context and priorities. The agent can read demographics, traffic counts, and nearby brands. What it needs is an explanation of how those matter to your concept, what "good" looks like for you, and what rules a site out.
Anything you'd give as context to a new team member belongs in the prompt. Anything you leave out is filled with generic retail assumptions.
Writing a Good Prompt
A good prompt narrows down in three passes. Start with what you want the evaluator for, turn that into specific criteria, then refine it as you use it.
1. Identify the goal of the prompt
Decide what the evaluator is for before you write anything else. Frequently, the goal is either broad or narrow.
Broad: a surface-level look at everything you care about, like demographics, traffic, and the competitive landscape. This suits quickly prioritizing which sites deserve a closer look.
Narrow: a deeper look at one aspect of a site. For example, how well it would serve a drive-thru, or how closely the trade area matches your ideal customer.
Keep each evaluator to one goal, and state it early in the prompt. A prompt that asks "Is this a good fit for our brand?" and "Is this a good drive-thru site?" at once would be better as two different evaluators.
2. Identify the criteria that meet that goal
Next, break down the goal into guidelines the agent can apply. If the goal is judging demographics, name which demographics you care about and what good amounts of each look like.
Give the context the goal needs. Include business context the data sources don't already carry, and only as much as serves the goal. A demographics evaluator needs your ideal customer profile. A drive-thru evaluator needs your lane and stacking requirements.
Our ideal customer is a family household aged 30–50, earning $75k–$150k.
Name your criteria and rank them. List what the agent should weigh, most important first. Without a ranking, every criterion counts the same.
In order of importance: household income in the trade area, weekday traffic on the adjacent road, and distance to our nearest existing store.
Say what good looks like. A criterion without a threshold forces the agent to guess what's high or low. Give numbers wherever you have them, even rough ones.
Weak: "Consider household income."
Strong: "Median household income above $90k is strong for us. Below $60k is a concern."
Your own portfolio is the best source for these numbers. If your top stores all sit in trade areas above a certain income, say so.
Name the dealbreakers. Some things rule a site out no matter how strong it is elsewhere. Name them, and say what they do to the rating. A dealbreaker the prompt doesn't name gets averaged in with everything else.
If an existing store of ours is within 3 miles, rate the site no higher than 2, however strong the other criteria are.
Define the scale. Say what separates a top rating from a middle one from a bottom one. This is what spreads your ratings out. Without it, most sites land in the middle.
Say what to leave out. If something doesn't matter to your concept, say so. A late-night bar doesn't care about daytime foot traffic. Leaving it out keeps the reasoning on what does matter.
Use plain, specific language. Swap vague words like "good" or "appropriate" for what you actually mean. Write "under 5 minutes from a highway exit," not "good access."
3. Refine as you go
A prompt doesn't need to be perfect the first time. As you use the evaluator, you'll spot gaps: a criterion it keeps missing, a concern it overweights, a dealbreaker it lets through. When you notice one, edit the prompt to cover it. Locations re-evaluate with the updated prompt.
Read the reasoning, not just the rating. It shows what the agent weighed and what it didn't, which is usually where a gap shows up. See Improving a Prompt for common issues and fixes.
Parts of a Prompt
Most strong prompts carry the same parts, in roughly this order. Use this as a checklist, not a form. A narrow evaluator may only need three or four of these.
Goal
What this evaluator is for
Context
Business context the goal needs, like your ideal customer profile
Criteria
What to weigh, most important first
Thresholds
What counts as strong or weak for each criterion
Dealbreakers
What caps the rating, and at what
Scale
What earns a top, middle, and bottom rating
Out of scope
What to ignore
Writing for Custom Evaluators
A custom evaluator's prompt goes in Instructions. See Creating an Evaluator for where to find it.
Everything goes in Instructions
Everything that shapes a rating goes in Instructions. Purpose describes the evaluator for your team. Criteria written there don't reach the evaluation.
Tie each criterion to a data source
The evaluator only sees the data sources you've added. Name the source next to the criterion it answers. That tells the agent where to look and makes a missing source easy to spot.
Use Demographics Data to judge household income. Use Vehicle Traffic for road counts. Use Cannibalization Data for overlap with our stores.
A criterion with no source behind it gets scored from the address alone. Either add the source or drop the criterion. Add only the sources your criteria use to avoid diluting the important data.
Examples
These examples use a fictional fast-casual restaurant brand. The first is a broad evaluator. The other two are narrow evaluators. Swap in your own concept, numbers, and field names.
A broad fit evaluator
This evaluator takes a surface-level look at the whole site: is this a good site for the brand? It has Demographics Data, Vehicle Traffic, Nearby Businesses, and Cannibalization Data added.
A demographics evaluator
This evaluator answers one question: does the trade area match our ideal customer? It only has Demographics Data added.
A competitive landscape evaluator
This evaluator judges the brands around a site. It only has Nearby Businesses added.
Improving a Prompt
When results don't match what you expect, the reasoning usually points to the cause.
Most sites get the same middle rating
The scale doesn't say what separates the levels
Define what earns each rating, with thresholds
The reasoning never mentions a criterion
No data source covers it, or it's buried in the prompt
Add the source, name it next to the criterion, and move it up the list
A site with a known dealbreaker still rates well
The dealbreaker isn't named, or its effect isn't stated
Name it and say what rating it caps at
The reasoning lists figures without judging them
The prompt gives no thresholds
Say what counts as strong and weak for each figure
The reasoning dwells on something you don't care about
Nothing says to ignore it
Add it to what's out of scope
Ratings look reasonable but disagree with your team
The criteria or their ranking don't match how your team decides
Ask a colleague to explain their call on a site, then write that down
The run fails
A data source couldn't answer for that location
Remove sources your criteria don't use
An evaluator tries to answer everything
It's asking more than one question
Split it into a broad evaluator and narrow ones
Writing for Site Score Lenses
The advice above is written for custom evaluators, but it applies to Site Score lenses too, with some adaptation. Lenses are edited in the Site Score tab of Workspace Settings.
The lens description is the prompt. Write it as the prompt for that one dimension.
Workspace Context is shared by every lens. Describe your concept and customer there once, instead of repeating it in each lens.
One dimension per lens. Keep each lens to its own question. The overall score combines them.
Weight handles importance between lenses. Rank criteria inside a lens description. Use the lens weight to make one lens count more than another.
Lenses score from 0 to 100. Write thresholds and the scale against that range.
Connect the data a lens needs. A lens with no data sources gives a best-effort estimate from the address.
Related Features
Custom Evaluators — creating, running, and managing evaluators
GrowthFactor Score — the lens-based site score
Workspace Settings — where evaluators and lenses are configured
Last updated
Was this helpful?