Who this is for: self-serve plans (Free, Starter, Pro, Scale). If you bought a Cleanlist AppSumo lifetime deal, your features, limits, and pricing are different — see the AppSumo documentation instead. Support agent: confirm whether the user is self-serve or AppSumo before giving plan-specific advice.
TL;DR: Three agents. Research (3 credits for company or contact, 5 for both) investigates on the live web. Qualification (5 credits) scores against your ICP and checks your CRM. Custom (3 credits at ≤500 prompt tokens, 5 above) runs a prompt you save once. All three read your Organization Profile, which is free to build. Starter and above, and every AppSumo tier.
Agents
Agents do the reading and the judging that a rep would otherwise do by hand. You point one at a lead list, it works row by row in the background, and it writes results back as new columns.
Open them from the Agents page in the left nav, or from the Agents tab of the Actions drawer inside any lead list.
The three agents
| Agent | What it does | Credits per lead |
|---|---|---|
| Research | Investigates the company, the contact, or both on the live web and returns structured fields plus a written brief | 3 (company) · 3 (contact) · 5 (both) |
| Qualification | Scores the lead against your Organization Profile and checks whether the person is already in your CRM | 5 |
| Custom | Runs a prompt your team writes and saves, against every row | 3 (prompt ≤500 tokens) · 5 (above 500) |
Agents are available on Starter and above on self-serve, and on every AppSumo tier. They are not available on the Free plan.
Before you start: the Organization Profile
Agents are gated behind a one-time setup. Until someone in your organization completes it, the Agents page shows the setup card instead of the catalog.
Give Cleanlist your company website and, optionally, your company LinkedIn URL. Cleanlist reads your homepage and runs deep web research to draft a structured profile of what you sell and who you sell to:
| Field | What it holds |
|---|---|
company_name, one_liner, industry | Who you are, in one line |
icp | Your ideal customer profile, in prose |
personas | Titles and roles you sell to |
personas_excluded | Titles you never sell to |
value_props, products | What you pitch |
competitors | Up to 10 |
geo_focus | Your markets, in prose |
geo_countries, geo_states, geo_cities | Structured include and exclude lists |
Three things worth knowing:
- Building the profile is free, every time, including rebuilds. It does not touch your credit balance. The only limit is 6 rebuilds per hour per organization.
- One person unlocks it for everyone. Onboarding is completed once per organization, not once per user.
- First-time setup is open to any member. Rebuilding it is admin only. Editing individual fields on the Profile tab is also admin only.
Setup runs synchronously and can take up to four minutes, because the research is real.
Get the exclusion lists right. personas_excluded and the geographic exclude lists are the only part of the profile that can disqualify a lead before any model runs, which makes them the cheapest filter you have.
Research
Point Research at a list and it investigates each row on the live web, then writes back both a structured record and a readable analysis.
Scope. Three options, set with the pills in the run panel. On the Companies sheet the scope is fixed to Company.
| Scope | Credits per lead |
|---|---|
| Company | 3 |
| Contact | 3 |
| Both | 5 |
How it works. Research is a tool-using agent, not a single model call. Per lead it may:
- Run up to 6 web searches
- Fetch full pages and read them
- Check your connected CRM
It is required to complete at least two investigation steps before it is allowed to answer, and it runs for at most eight turns.
What you get back, on Company scope: company name, one-liner, industry, employee-count estimate, founded year, HQ location, products, positioning, recent news (up to 5), hiring signals, tech stack, funding rounds (up to 8), and competitors (up to 10).
What you get back, on Contact scope: full name, current role, tenure in months, prior companies (up to 8), areas of responsibility, public content (up to 8), and talking points.
Open any cell to see three things: the written analysis, a Structured insights panel where you can promote any single field to its own column, and an Agent trace showing each search and fetch the agent performed. Trace excerpts are redacted of personal data and truncated.
Qualification
Qualification answers two questions in one pass: is this lead worth working, and do we already own them.
It runs in three stages, in this order.
1. Exclusion pre-check, no model call. If the lead's job title matches an entry in your excluded personas, or their country, state, or city matches a geographic exclude entry, the lead is disqualified immediately with fit_score: 0 and the reason attached. Exclusions beat inclusions. This stage still costs 5 credits, because credits are reserved before the run starts.
2. CRM presence check. Cleanlist queries every CRM you have connected in parallel, with a 5 second timeout each, and takes the first non-error match. Supported CRMs are HubSpot, Salesforce, and Lemlist. A HubSpot connection made by any teammate counts for the whole organization; Salesforce and Lemlist are per organization.
3. ICP scoring. The model scores the lead against your Organization Profile. The real CRM result is passed in as known context and is written back over whatever the model says, so the CRM field is never a guess.
What you get back:
| Field | Values |
|---|---|
fit_score | 0 to 100 |
verdict | qualified, disqualified, needs_review |
verdict_reasons | 1 to 4 short bullets |
crm_status | An existing match with CRM type, record URL, record id, and owner; or a confirmed absence; or a lookup failure |
disqualification_flags | Any of: competitor, partner, current_customer, sub_icp_size, geo_mismatch, wrong_persona, no_business_signal |
analysis | Written rationale |
Qualification does not search the web.
Custom agents
Write a prompt once, save it, and anyone on your team can run it on any list.
Creating one. On the Agents page, under Your custom agents, give it a name, an optional description shown on the card, and the prompt. There is a Generate button that drafts a prompt from a plain-English description of what you want. Creating, editing, and deleting custom agents is admin only, and names must be unique within your organization. Deleting an agent removes the saved prompt but keeps every result it already produced.
You can also save a one-off prompt from the run panel without spending a run, using Save settings only.
Cost. 3 credits per lead when the resolved prompt is 500 tokens or fewer, 5 credits above that. The run panel shows a live token count and the resulting price before you run. The hard ceiling on any resolved prompt is 8,000 tokens.
Output. A single value: text, a list, a true/false, a number, or a set of key-value pairs. Cleanlist picks the shape from your prompt.
What Custom agents do not do. Unlike Research, a Custom agent does not search the web, does not fetch pages, does not query your CRM, and does not read your Organization Profile. It sees only the lead, prospect, and company data already on the row. If you need live research, use the Research agent.
Referencing row data in a prompt
The syntax is not the same on all three agents. This is the single most common way to waste credits, so check it before a large run.
Research and Qualification resolve {{namespace.field}} tokens. Type / in the prompt editor and pick from the list; the editor inserts the correct token. The variables are grouped into lead, prospect, company, and org_profile:
| Group | Examples |
|---|---|
lead | lead.first_name, lead.last_name, lead.full_name, lead.email, lead.job_title, lead.linkedin_url, lead.location |
prospect | prospect.linkedin_url, prospect.headline, prospect.summary, prospect.location |
company | company.name, company.website, company.industry, company.employee_count, company.hq_location, company.description |
org_profile | org_profile.icp, org_profile.personas, org_profile.value_props, org_profile.competitors, and the geographic include and exclude lists |
Custom agents resolve a different syntax: a forward slash followed by the display label of the field, capitalized, with spaces.
| Write this | Not this |
|---|---|
/First Name | /first_name |
/Job Title | /title |
/Email | /primary_email |
/Company Name | /company_name |
/Company Domain | /company_domain |
/LinkedIn URL | /linkedin_url |
The full set of labels is: First Name, Last Name, Full Name, Job Title, Email, Phone, LinkedIn URL, Company Name, Company Domain, Industry, Company Size, City, State, Country, Full Location, Created Date, plus the name of any custom column on your list.
A reference that does not match a known label resolves to an empty string, silently. The run still costs full price. {{ }} tokens do not resolve on Custom agents either — they are sent to the model as literal text. Test any new prompt on a handful of rows and read the output before scaling it.
Running an agent on a list
Open a lead list, open the Actions drawer, and pick the Agents tab. In the run panel you can:
- Target selected rows, all unfilled rows, or re-run everything
- Add an Only run if condition so the agent skips rows that do not match
- Turn on auto-update so new rows added later are processed automatically
- Pick the scope, for Research
- Edit the prompt for this run only, or save it as your organization's default
The panel shows the exact credit cost before you run. Runs are capped at 20 per minute per organization.
Each row moves through Pending, Processing, then one of Completed, Partial, or Failed. Partial means some fields were filled and some failed on that row.
Editing the default prompts
Each built-in agent has a default prompt, and Research has a separate one per scope. Admins can override the default for the whole organization from the Profile tab. Members see the resolved prompt and can edit it for a single run without changing the default.
Related
- Cleanlist Copilot — launch agents in plain language
- List actions — the validation and enrichment columns
- Agent recipes — four working setups
- Credit pricing
- CRM integrations — the connection Qualification checks