Giving an AI employee reference files to read
A price list, a product catalogue or your rules for a good customer can sit beside the AI as it works. Which files help, how to write them, and what never to upload.
Part of the guide AI employees
You give an AI employee reference files by attaching them to its xMap LLM step: documents such as your product catalogue, price bands, the rules your team uses to judge a good customer or the areas you serve. The AI reads them alongside the data the flow found and uses them in its answers, so a score or a product suggestion follows your rules rather than a general idea of a good business. Short, plain, well-organised files work far better than long ones.
This article is for anyone who has an AI employee scoring places, matching products or writing summaries and wants its answers to sound like their own team. It covers what reference files are for, which documents help, how to prepare them, a made-up example, and the mistakes that make answers worse rather than better.
What a reference file does
Without reference files, the xMap LLM step knows two things: your instructions, and what the blocks before it found about each place (name, kind, rating, address, website and so on). It can judge a cafe as a lively, well-rated business, but it cannot know that your coffee machines suit cafes with more than 20 seats, or that you never sell north of the river.
A reference file closes that gap. Attached to the step, its text is read with every batch of places, so the AI can say "suits the compact model, under your mid price band" instead of "seems a good fit". The step reads PDF, TXT, CSV, Markdown and JSON files of up to 3 MB each, and takes in about 40,000 characters of text from up to 10 files. Past that, the rest is not read.
There is also a shorter way: the step's reference notes, a box for a few lines the AI should always keep in mind. Use the notes for three or four rules and files for anything longer.
Documents that make answers better
- A product catalogue or range sheet. With the Match products task, the AI suggests which of your products suit each place and a first order. Keep one line per product: name, who it is for, size or volume.
- Your ideal customer, written down. Most teams know it but have never written it. One page on what makes a strong account and what makes a poor one turns a vague score into one your reps recognise.
- Price bands or service tiers. So the AI can say which tier fits, not just whether to call.
- The areas you cover. Districts, postcodes or towns by team, so the summary says who should take the lead.
- A scoring rubric. Points for each sign you care about. The AI will follow a clear rubric more consistently than a paragraph of preferences.
How to write a file the AI reads well
- Write for a new colleague on their first day: short sentences, one idea each, no internal shorthand they would not understand.
- Put the rules first. If something must always or never happen, say it in the first lines.
- Use headings and lists. A file with a heading per product or per tier is easier to use than a wall of text.
- Remove what does not help the decision: history, mission statements, legal footers. They use up the characters the AI reads.
- Save it as text where you can. A scanned page that is only a picture holds no text for the AI to read; export or retype it.
- Test it. Run the flow once on a handful of places and read the reasons. If the AI quotes the wrong rule, the file is unclear there.
A made-up example in Cape Town
An invented case. A wine distributor in Cape Town has an AI employee that finds new restaurants every week and scores them as accounts. Without reference files, its reasons say things like "popular restaurant, likely to stock wine". The sales manager writes a one-page file called our_good_accounts.md:
- Strong: sit-down restaurants with a full menu, rated 4.3 or more, open in the evening, within our three delivery zones.
- Weak: takeaway counters, cafes that close before 6 pm, places outside the delivery zones.
- Our ranges: an entry range for casual dining, a cellar range for fine dining. Never offer the cellar range to a place rated under 4.5.
She also attaches the price list as a CSV. The next run's reasons read: "Strong: evening sit-down, rated 4.6, inside zone 2. Suggest the cellar range." and "Weak: closes at 4 pm, a cafe." The scores did not become magic; they became the team's own rules applied to every new place, the same way every week.
Mistakes that make answers worse
- Uploading everything. Ten long brochures fill the reading limit with marketing text and leave little room for the rules that matter.
- Contradictions. A file that says "any size" on page one and "over 20 seats only" on page five gets answers that wobble between the two.
- Using a file as a database. A list of 3,000 existing customers is a table, not a reference file. To leave out your customers, put the list in My data and use Match with my table, which checks every place exactly.
- Expecting facts the data does not hold. A rule about a restaurant's turnover cannot be applied if nothing in the flow says what the turnover is. The AI is told to say when something is unknown rather than guess; check reasons that say so.
Putting it to work
- Open the flow and select its xMap LLM step, or add one after the data blocks.
- Pick the task: Score & rank, Match products, Write summary, Classify or Extract fields.
- Write the instructions, then attach your reference files and add any short rules as reference notes.
- Run the flow once and read the reasons; adjust the file, not just the instructions, where a reason is wrong.
- Add Sort and limit on the score and send the result by Email or to a sheet.
From then on, each run's results arrive scored and explained in your team's words, and when your ranges or rules change you replace one file instead of rewriting every instruction.
Questions
Which file types can an AI employee read?
PDF, TXT, CSV, Markdown and JSON files of up to 3 MB each. About 40,000 characters of text are read from up to 10 files.
Should I attach my customer list as a reference file?
No. Upload it as a table on the My data page and use Match with my table, which checks each place against every row exactly.
Why does the AI ignore part of my file?
Usually because the file is too long and that part falls past what is read, or because the rule is buried or contradicted elsewhere. Put rules first and keep the file short.
Are reference files the same as asking about company files?
No. Reference files sit beside one AI step in a flow. Ask xMap's company file search answers questions from your organisation's files in the assistant, which is a separate feature.
Templates that do this
Read next
More on ai employees and automation · Every article · Templates