Writing good instructions for an AI that scores places

Good scoring instructions describe the place you want and the place you do not, in the words of the fields the AI can actually see. Say what an ideal result looks like, name two or three things that make a place a poor fit, tell it which facts to weigh most, and keep it short. A sentence like "independent cafes on busy streets that roast nothing themselves are ideal; chain branches and hotel cafes are not" moves the ranking more than a page about your company.

This article is for anyone setting up an AI step that gives each place a score from 0 to 100 and a one-line reason: sales teams ranking prospects, expansion teams ranking sites, buyers ranking suppliers. It covers what the AI reads, the shape of instructions that work, a before-and-after example, and how to check the result.

What the AI can and cannot see

In xMap Flows the scoring is done by xMap LLM with the task Score and rank. It reads every field the blocks before it found about each place: name, category, rating, number of reviews, address, website, whether it belongs to a chain, how many similar places are nearby, residents around it, and anything else earlier blocks added. It works through the list in batches of 25, up to 500 places a run, and writes a fit score from 0 to 100 and a short reason on each.

It cannot see what is not in those fields. If no block counted the offices around each cafe, an instruction to favour cafes near offices has nothing to work on, and the reasons will say so or guess from the name. The fix is a block, not a longer sentence: add a count of offices with Nearby places before the scoring step.

The shape of instructions that work

1. Say who you are in one line. "We roast coffee and sell beans wholesale to cafes."
2. Describe the ideal place. "Independent cafes with many reviews, rated 4.3 or more, that do not roast their own beans."
3. Describe a poor fit. "Chain branches, cafes inside hotels or malls, and anything that is mainly a bakery."
4. Say what matters most. "Weigh independence first, then reviews, then rating."
5. Say how to use the range. "Give 80 or more only to places we should visit this week."

Five short sentences are usually enough. Long product descriptions, mission statements and lists of every service you offer dilute the signal, because the AI tries to use all of it.

Why rating alone rarely separates anything

Ratings bunch at the top in many markets, so an instruction like "prefer well-rated places" can end up meaning almost nothing. xMap's places database shows how uneven this is. It lists 830 dentists within 10 km of the centre of Toronto; of the 460 nearest the centre, 366 have a rating, averaging 4.7 out of 5, and 313 are rated 4.5 or more. It lists 1,332 supermarkets within 10 km of the centre of London; of the 437 nearest the centre, the 423 with a rating average 3.6, and only 38 are rated 4.5 or more (November 2026).

313 of 366Toronto dentists rated 4.5 or more

38 of 423London supermarkets rated 4.5 or more

So "rated 4.5 or more" keeps most Toronto dentists and almost no London supermarkets. Be specific about what rating means for your market, or weigh the number of reviews alongside it: a 4.9 from twelve reviews tells you less than a 4.4 from six hundred. See the Toronto dentists and London supermarkets pages.

Before and after: a coffee roaster in Melbourne

Say a roaster in Melbourne scores 200 cafes a month. Its first instructions read: "Score how good a customer each cafe would be for our premium specialty coffee. We value quality, sustainability and great partnerships." The top 20 came back full of chain branches with thousands of reviews, because nothing said chains were a poor fit, and the reasons all said some version of "popular cafe with strong reviews".

The rewrite: "We sell beans wholesale to independent cafes. Ideal: independent, 4.3 or more with at least 100 reviews, a website that does not mention roasting. Poor fit: any chain, cafes inside hotels or shopping centres, places whose category is bakery or restaurant. Weigh independence first. Give 80 or more only to cafes worth a visit this month." The next run's top 20 had no chain branches, and the reasons named the fields that drove each score. The numbers in this example are made up; the pattern is what to copy.

Checking the scores before you trust them

• Read the top ten and the bottom ten. If you would swap any of them, your instructions are missing the reason why.
• Ask why. Every result has an Ask why button; it explains a score from the place's facts and your instructions in a few sentences.
• Run a test first. A test run scores on real data and sends nothing.
• Keep the step that uses the score simple. After scoring, a Filter on Fit score keeps the strong ones and Sort and limit keeps the top N.

The AI does not learn from which results your team acts on. If the ranking drifts from what you want, change the instructions: open the block, or reply in the employee's Team inbox thread with something like "score chains below 30 from now on".

When a score is the wrong tool

If your question is yes or no ("does this place serve breakfast?") or pick one of a fixed list, a score adds noise. Use the Classify task with your labels, or Jev decision for one typed question per place. Save the 0 to 100 score for genuine rankings where order matters. And if a rule can be written as a filter (rating at least 4, independents only), use the filter: it is exact, free of judgement and easy to read later.