This article picks up where What is Clay? leaves off. It is about the engineering around the prompt: choosing the right tier of AI, writing the column as a contract, grading it before you trust it, and keeping the cost predictable.
First decide whether you need an agent at all
The most expensive Claygent column is the one that shouldn't exist. Clay's own credit guidance sorts AI work into three tiers (Clay University):
| Tier | Tool | Use it when | Clay's framing |
|---|---|---|---|
| 1 | AI formulas | Reshaping, cleaning or summarising data already in the table | The lesson describes these as free, no credits required |
| 2 | Use AI | You need judgment or classification, but not the internet | Best "when you need reasoning and don't need the Internet" |
| 3 | Claygent | The answer only exists on the live web | Deploy it "when you need the internet" |
Most columns labelled "AI research" are tier-one work running on tier-three infrastructure. Before you write a Claygent prompt, ask three questions in order:
- Is the answer already in the row? Then it is a formula.
- Is the answer derivable from the row by reasoning? Classifying an industry from a description, normalising a job title, deciding whether a title is a decision-maker — that is Use AI, not web research. Clay documents Use AI as supporting GPT, Claude and Gemini models, with the option to connect your own API key to reduce cost (Clay docs).
- Does the answer live on a page somebody would have to open? Now you have a Claygent job.
That triage is the single biggest cost lever in Clay, and it is free to apply.
The MitHub Research Column Contract
A research column is not a question. It is a contract with six clauses. Write all six, in this order, before touching the builder.
- Input. Exactly which columns the agent may use, named. Not "the company" — "the domain in
Company Domain." - Question. One question. If your prompt contains "and also," split the column.
- Where to look. Name the sources you trust and the ones you don't. "Use the company's own website and its careers page. Do not use directory listings or aggregator sites."
- Output shape. A fixed structure: an enum, a number, a short list. Never free prose in a column that will be scored or routed on.
- Evidence. A required URL field for the page the answer came from.
- The unknown floor. An explicit, penalty-free way to fail: "If the company's own site does not state this, return
unknown. Do not infer."
Clause 6 is the one people leave out, and it is the one that causes damage. A model asked a question with no legal way to say "I don't know" will produce an answer anyway. You will not be able to tell that answer apart from a real one, because both arrive in the same column, in the same format, on the same day.
Fields, not paragraphs
Clay's Use AI documentation describes two ways to force structure: Fields, which produce named outputs with specified data types across multiple columns, and a JSON Schema option (Clay docs). Use them. A column that returns {locations: 14, evidence_url: "...", confidence: "high"} can be filtered, scored and audited. A column that returns three sentences of prose can only be read.
The rule we teach: if a human has to read the cell to use it, the column is not finished.
Build it in the builder, not in the table
Clay's Claygent Builder is documented as the central place to build, test and deploy agents, with three useful properties for anyone running more than one table (Clay docs):
- Free testing. Up to 10 inputs per agent, and the docs state test runs do not consume credits. You can import real rows from a table, save test suites, and compare outputs across models side by side.
- One definition, many tables. An agent built in the builder is a single source of truth: update it once and the change propagates wherever it is deployed, instead of living as a prompt pasted into six tables that have quietly drifted apart.
- Skills. Reusable methodologies that teach agents how you want a kind of work done. They are workspace-level, loaded only when needed, and the docs say they don't cost extra to run.
The docs also describe Sculptor, a conversational way to draft an agent — you describe the job in natural language and it generates the prompt, variables, output format and test cases. Treat that output as a first draft of the contract above, not as the contract. Sculptor is very good at producing something plausible; only you know which sources you trust and what "unknown" should mean.
On models, Clay groups the options into frontier models, open-weight models, and Clay-managed models (documented as Neon and Argon). The specific list changes, so check the page rather than memorising it — and use the side-by-side comparison rather than assuming the biggest model wins. On a narrowly scoped extraction question with a locked output shape, a smaller model often matches a larger one at a fraction of the cost, and the side-by-side test is how you find out.
One structural fact worth designing around: Clay describes general Claygents as stateless, one-shot operations (Clay). Each row is researched from zero. The agent does not learn from row 400 that row 12 was wrong. Everything it knows has to arrive in the prompt or the input columns — which is exactly why skills and a fixed contract matter more than clever phrasing.
The 25-row golden set
This is the part nobody does, and it is the part that turns an AI column into evidence you can defend. Before a research column influences a score, a message or a routing decision:
- Pick 25 rows on purpose. Not the first 25. Include 5 you know the answer to, 5 that are edge cases, 5 tiny companies, 5 non-English sites, and 5 at random.
- Answer them yourself first, by hand, before you look at the column. This is the step people skip, and skipping it means you are grading the model against your memory of what it said.
- Run the column and grade every row into one of four buckets.
- Set an acceptance gate before you look at the results, so you can't move the goalposts.
- Rerun after every prompt change on the same 25 rows.
The four failure modes, which need different fixes:
| Grade | What it means | The fix |
|---|---|---|
| Correct | Right answer, right source | Nothing |
| Wrong | Confident and incorrect | Narrow the allowed sources, or split the question |
| Over-cautious | Returned unknown when the answer was findable | The source list is too narrow, or the question is ambiguous |
| Unsupported | Right-looking answer, evidence URL doesn't contain it | The most dangerous one. Tighten the evidence clause and never let this column reach a prospect |
The unsupported bucket is why the evidence URL is mandatory. Without it, a wrong answer and a hallucinated answer look identical. With it, checking is a ten-second click.
Our default gate for anything that touches outbound copy: zero unsupported answers in 25, and over-cautious is always preferable to wrong. For a column that only feeds internal prioritisation, you can tolerate more error, because the cost of being wrong is a wasted call rather than a damaged reputation. Deciding that threshold consciously is what human in the loop is about.
Cost control that isn't guesswork
Clay meters platform work as Actions and purchased data or model usage as Data Credits, and its docs describe running enrichments only when a field is empty, the data is outdated or confidence is low, plus testing on a small batch before scaling (Clay docs). For research agents specifically, four habits do most of the work:
- Gate the column. Research runs only on rows that already passed the fit filter. An agent researching accounts you would never sell to is pure cost.
- One question per column. Cheaper to debug, cheaper to rerun, and you only rerun the clause that broke.
- Cache the obvious. If ten rows share a domain, research the domain once at the company level and join, instead of paying ten times for the same page.
- Downshift the model once the contract is stable. Lock the output shape first, then test whether a cheaper model holds the gate.
And the one that matters most: delete columns nobody used. Run a quarterly audit of every research column against the decision it was supposed to feed. In our experience the honest answer for a third of them is "nobody looked at it," and that is a finding, not a failure.
Where research agents fit in the bigger system
A Claygent column is one node in a chain: a list, an enrichment waterfall, research, a score, a destination. Its job is to produce facts that the scoring layer can use — which means the output shape should be designed backwards from the score, not forwards from curiosity. If the score needs a number of locations, the agent returns a number, not a paragraph about locations. That backwards discipline is the whole method in Follow the money, and it is how lead scoring in Clay stays explainable.
It also clarifies what Claygent is not. It is not an orchestrator. It does not retry across systems, wait for approvals, or route work between apps — that belongs to a workflow tool, as Clay vs n8n sets out. And it is not an autonomous agent in the sense described in what is an AI agent: a stateless, one-shot research call with a fixed output schema is closer to a very capable lookup than to something making decisions on your behalf.
That is a feature. The narrower the job, the easier it is to prove the column is right — and a column you can prove is right is the kind of work that belongs in a portfolio. Document the contract, the golden set and the grades, and you have a proof-of-work artifact, not just a table.