> For the complete documentation index, see [llms.txt](https://docs.growthfactor.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growthfactor.ai/guides/writing-evaluator-prompts.md). # 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](#examples) · [Improving a Prompt](#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](#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. | Part | What it covers | | ---------------- | ----------------------------------------------------------------- | | **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](/data-and-analytics/custom-evaluators.md#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. ``` Judge whether this location is a good site for a new store. We run 2,400 sq ft fast-casual restaurants with a drive-thru. Most sales are weekday lunch and dinner. Our best stores sit on commuter roads in suburban trade areas with lots of family households. Weigh these, most important first: 1. Household income (Demographics Data). Median above $90k is strong. Below $60k is a concern. 2. Weekday traffic on the adjacent road (Vehicle Traffic). Above 25,000 vehicles a day is strong. Below 10,000 is weak. 3. Overlap with our existing stores (Cannibalization Data). Under 10% is fine. Over 25% is a serious concern. 4. Co-tenancy (Nearby Businesses). Grocery anchors and big-box retail nearby are a plus. Dealbreakers. If either applies, rate no higher than 2: - Overlap with one of our stores above 35%. - The notes say there is no room for a drive-thru lane. Ignore weekend and late-night activity. They're a small share of our sales. ``` ### A demographics evaluator This evaluator answers one question: does the trade area match our ideal customer? It only has **Demographics Data** added. ``` Judge how well the trade area's population matches our ideal customer. Rate the people only. Ignore traffic, competition, and the site itself. Our ideal customer is a family household aged 30-50 with a median household income of $75k-$150k. Weigh these, most important first: 1. Median household income. $75k-$150k is our range. Above $150k is fine but not a plus. Below $60k is a strong negative. 2. Age. A large share of adults aged 30-50 is strong. 3. Population. Below 20,000 in the trade area is too thin to support a store. ``` ### A competitive landscape evaluator This evaluator judges the brands around a site. It only has **Nearby Businesses** added. ``` Judge the competitive landscape around this location, for a fast-casual restaurant with a drive-thru. Direct competitors are other fast-casual and quick-service brands with a drive-thru. Complements are grocery stores, big-box retailers, and gyms. They bring the daytime traffic we rely on. Weigh these, most important first: 1. Complements. At least one grocery or big-box anchor nearby is strong. None is a concern. 2. Direct competitors. One or two show the area supports the category. Five or more is saturated. 3. Whether a competitor is one of the brands we lose to most: Brand A and Brand B. Either one within a half mile is a concern. ``` *** ## Improving a Prompt When results don't match what you expect, the reasoning usually points to the cause. | What you see | Likely cause | What to change | | ------------------------------------------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------------- | | 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](/getting-started/workspace-settings.md#site-score-tab). * **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](/data-and-analytics/custom-evaluators.md) — creating, running, and managing evaluators * [GrowthFactor Score](/data-and-analytics/growthfactor-score.md) — the lens-based site score * [Workspace Settings](/getting-started/workspace-settings.md) — where evaluators and lenses are configured --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.growthfactor.ai/guides/writing-evaluator-prompts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.