> 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/data-and-analytics/custom-evaluators.md). # Custom Evaluators A custom evaluator is an evaluator agent your team writes. Each one scores a location against criteria you define. It reads your instructions, pulls in whatever real data you give it access to, and returns a rating with the reasoning behind it. Evaluators run in studies on pins, on your existing stores, and on deals. {% hint style="info" %} **Early Access Beta:** Custom Evaluators is in early access beta. {% endhint %} *** ## Creating an Evaluator Evaluators are configured per workspace, in the **Custom Evaluators** tab of [Workspace Settings](/getting-started/workspace-settings.md#custom-evaluators-tab). Workspace Settings is admin-only, so admins write and manage the evaluators. Everyone with access to the workspace sees them and can run them on a location. A new sub-workspace starts with a copy of its parent's evaluators. The copies are independent of the originals. Click **New evaluator** to create one, or pick an existing evaluator from the **Evaluator** dropdown to see its configuration. * **Name** — the name for the evaluator, showed in dropdowns and exports. * **Purpose** — a short description of what this evaluator judges. * **Instructions** — what the evaluator should weigh when it scores a location. Write it the way you'd brief an analyst. See [Writing Evaluator Prompts](/guides/writing-evaluator-prompts.md). * **Data sources** — real data about the site it can pull in while scoring. See below. A new evaluator needs a name, a purpose, and instructions before **Create evaluator** is available. Once it exists, edits save on their own a couple of seconds after you stop typing. The status under the form reads **Saving…**, then **Saved**. Empty a field and it reads **Not saved — every field needs a value** instead. {% hint style="warning" %} If someone else changes the evaluator you're editing first, your save is refused and a dialog appears naming that evaluator. **Review theirs** loads what they wrote, discarding yours. **Override** saves your version over it. {% endhint %} ### The Workspace Default One evaluator per workspace can be the default. It's the one a location is evaluated with when you open its panel, and it sorts to the top of every evaluator picker with **· Default** after its name. Select an evaluator and click **Make default** to set it, or **Clear default** to unset it. The note to the left tells you where the selected one stands — **Locations in this workspace evaluate with this one.** or **Locations evaluate with the workspace default.** ### Data Sources Open the **Add data source** menu to give an evaluator real data to work from. Each source you add becomes a card. Click a card to expand it for a description of the source and its settings. Leave a setting empty and the evaluator falls back to your workspace's configured default, which the badge on the card reports as **Organization defaults** — or as a count, like **2 set**. | Data source | What it provides | What you can set | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | **Demographics Data** | Population, income and age around the site | — | | **Vehicle Traffic** | Traffic counts on nearby roads | Search radius, road type, hour of day | | **Foot Traffic** | Visit patterns at the site | — | | **Nearby Businesses** | Brands trading near the site | Businesses to include (1–100, default 20) | | **Cannibalization Data** | Trade-area overlap with your existing stores | — | | **Analog Stores** | Your stores most similar to this site | Store size | | **Zoning** | The zoning district at the site, the uses it allows, and its building limits | — | | **Web Search** | News and developments about the site and its area from the live web, such as proposed developments, openings and closures | Recency, in days | **Web Search** researches the site's location, guided by the evaluator's instructions. It only uses coverage from the last number of days you set under **Recency**. Enter 0 for any date. The trade area the area-based sources measure across comes from the workspace's default trade zone, in the **Defaults** tab. Change it there to change it for every evaluator. Remove a source with the **X** on its card. The **Add data source** menu only lists sources the evaluator doesn't have yet, so it disappears once all eight are added. An evaluator with no data sources still runs, and its card reads **No data sources yet. This evaluator will score on the location alone.** A source that can't answer fails the run rather than letting the evaluator score around missing data. Add only the sources the criteria actually need. ### Deleting an Evaluator Click **Delete** below the form and confirm. The evaluator stops appearing on locations. Evaluations it already produced stay in history. *** ## Running an Evaluator **Custom Evaluator Agents** is the first card in the operations list of a pin, an existing store, or a deal selected on the study map. On a pin, that list is the **Data** tab. Opening the panel evaluates the location with the workspace default, or with the only evaluator there is. Each result shows: * **Rating** — a badge carrying the evaluator's verdict, colored on the same Excellent / Great / Good / OK / Bad scale as the [GrowthFactor Score](/data-and-analytics/growthfactor-score.md). A number is read against its maximum, so a score out of five reads **4/5**. Word grades like **Strong** and letter grades like **B+** are colored too. A rating the scale can't place shows in grey. * **Justification** — the written reasoning, collapsed after three lines with a **Show more** toggle. * **Evaluated** — how long ago the result was produced. Where the workspace has more than one evaluator, a dropdown at the top of the card switches between them. Picking one that hasn't judged this location yet runs it. Admins also get a gear, **Manage evaluators**, that opens the Custom Evaluators tab. A location that's already been judged shows the verdict it has rather than spending a fresh run. Two locations at the same address share that verdict, so a pin you drop on a deal you already evaluated opens with the deal's result. Change the address, notes, or custom fields behind a location and it re-evaluates on its own, as does editing the evaluator itself. Click **Rerun evaluator** to score it again from scratch — use that when the standing result looks stale or wrong. A location this evaluator hasn't scored reads **Not evaluated yet**, with a **Run evaluator** button. A workspace with nothing configured reads **No evaluator agents**, and admins get a **Create evaluator** shortcut into Workspace Settings. ### Evaluation History Once a location has more than one run for the selected evaluator, **View past evaluations** appears at the foot of the card with the run count beside it. It opens the full history, grouped by day under **Today**, **Yesterday**, or the date. Each run lists the time it finished, its rating, how long it took, and its justification. The dropdown in the header switches evaluators without closing the dialog. *** ## In a Study Export A study's PDF carries evaluation history for the pins in it — a page per evaluator that has run on a pin, filed under that pin's own pages, with up to the eight most recent runs. Turn it off with **Evaluation history** under **Appendix** in **Export options**. Existing runs print as they stand — exporting never evaluates a location. Only the study's own pins are covered, not the stores and deals it borrows. See [Sharing and Exporting Studies](/study/sharing-and-exporting-studies.md#choosing-what-to-include). *** ## Custom Evaluators and Site Score Custom Evaluators is replacing the [GrowthFactor Score](/data-and-analytics/growthfactor-score.md). Where you have both, the **Site Score** tab in Workspace Settings carries a **Deprecated** label and a notice pointing here. Existing Site Score configuration keeps working. See [Changing Site Score to Evaluators](/guides/changing-site-score-to-evaluators.md) to rebuild your score as evaluators. *** ## Asking the Agent The agent can read your evaluators and run them. Try: * "What evaluators do we have?" * "Run the drive-thru evaluator on P1" * "Score these three candidates with our standard evaluator and compare them" It answers with the verdict a location already has rather than re-running one, so what it tells you matches what the card shows. Ask it to score a location again to force a fresh run. See [GrowthFactor Agent](/study/growthfactor-agent.md). *** ## Related Features * [Workspace Settings](/getting-started/workspace-settings.md) — where evaluators are written and managed * [GrowthFactor Score](/data-and-analytics/growthfactor-score.md) — the lens-based score Custom Evaluators replaces * [Pins](/study/pins.md) — the panel an evaluator runs from * [Cannibalization](/data-and-analytics/cannibalization.md) — one of the data sources an evaluator can use --- # 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/data-and-analytics/custom-evaluators.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.