How the import agent works
Behind the scenes of spreadsheet imports — what the AI agent sees, what it decides, and how to read its reasoning.
How the import agent works
When you drop a spreadsheet into the Import → Spreadsheet panel, Shortlistr runs a single long-running AI agent over the file instead of a fixed set of column rules. This page explains what that means in practice.
Why an agent?
ATS exports are inconsistent. The same idea — "the role this person currently has" — shows up as Title, Position, Current Role, Headline, or splits across Job Title + Company. Fixed rules either over-fit one ATS or get the rest wrong.
An agent reads the whole file in context — every header, sample values from every column, column-level statistics, and a snapshot of the candidates already in the role — and decides what belongs where. Because it sees the file as a whole, it can revise decisions on later rows based on patterns it noticed earlier.
What the agent sees
For each import the agent receives:
- The file name and sheet name
- Every header, in order
- A sample of rows (with all cells)
- Per-column statistics (fill rate, unique values, value lengths, detected types)
- The current canonical candidate schema
- A summary of candidates already in this role (for deduplication)
It does not see other roles in your workspace, other users' data, or any file other than the one you uploaded.
What the agent can do
The agent uses a small, fixed tool kit:
| Tool | Purpose |
|---|---|
inspect_column | Pull more sample values from a specific column |
lookup_existing_candidate | Check whether a row matches a candidate already in the role |
propose_new_field | Suggest a structured "extra" field for data that doesn't fit the canonical schema |
emit_candidate | Output one parsed candidate row with reasoning + confidence |
flag_row | Mark a row as unparseable, with a reason |
finish | End the run with a summary |
Every emit_candidate call becomes one row in the review table. The agent's reasoning is stored alongside it and shown in the ? tooltip.
Confidence
Each emitted row carries a confidence score. Use it as a filter, not a hard cutoff — a 0.6 row on an unusual column is often correct, just worth a glance. The Low confidence chip in the review table groups these for you.
Schema extensions
When the agent sees data that doesn't fit any canonical field — visa status, salary expectations, recruiter notes, custom scorecards — it can propose_new_field. Proposed fields appear in a banner above the review table:
- Accept — the field is stored as a structured extra on every matching candidate.
- Reject — the column is dropped for this import.
Accepted extras are saved into the candidate's raw_extras so you can search and filter on them later.
Deduplication
Before emitting a candidate, the agent calls lookup_existing_candidate for any row with an email or LinkedIn URL. Matches show as a Dupe badge with a link to the existing candidate. Importing a duplicate merges new fields into the existing record without overwriting anything you've already edited.
Limits
- 150 rows / 10 MB per file today. Larger files are coming.
- One agent run per upload. If you change the file, re-upload.
- The agent is read-only against your candidate list — nothing is written until you click Import.
Quality bar
Every change to the agent prompt is run against an internal fixture pack covering Greenhouse, Lever, Ashby, LinkedIn Recruiter, and intentionally messy in-house exports. We only ship changes that keep precision and recall above our internal bar across the whole pack.