How to tell AI agents what your CRM fields mean

By Izzy Aly, Co-Founder, Systems and Architecture


You run operations, your team already has Claude or ChatGPT, and connected it to your CRM. So you try it on the question your head of sales asks every Monday: "Which deals will close this month?"

The agent goes into your CRM and gets the open deals. It weights each one by its stage probability, so every deal in Contract sent counts at 90%, HubSpot's default for that stage. Nobody told it that in your team, that stage only means the order form has gone out and the buyer's legal team hasn't replied yet.

So the forecast your head of sales gets back looks close to target. But it includes deals that will still be waiting on the buyer's legal team when the month ends, and nobody sees the gap until they slip into next month.

The data in your CRM was fine. The agent did what a new hire does with a field nobody explained: it picked the most likely meaning and carried on as if it knew.

The fix is a field dictionary, one shared document that says what each field your agents read means in your team. It also lists which values are allowed, which tool wins when two tools disagree and who may change each field.

You start with the fields one job needs, meaning one task you hand the agent, such as the Monday forecast. Each new job then adds its own fields to the same document.

This guide shows how to write the first version in a day without restructuring your CRM. It also shows where to keep it so every agent you use reads it, including the one built into your CRM. The template, the interview prompt and twelve test questions are in our free field dictionary kit, along with a skill that tells your team's agents to read it before any task on deals.

Key takeaways

  • A connector gives the agent the value in each field, such as a deal's Weighted amount, which HubSpot works out from the deal stage's probability, but not what that value means in your team. So its forecast looks right even when it isn't. Until the meanings are written down, someone has to check every answer, which means the agent hasn't taken any work off your team yet.
  • A clean CRM wouldn't have fixed the Monday forecast. Every deal can have the right stage and amount, and the agent still won't know what those stages mean in your team. If you wait for a full clean-up first, the job you wanted to hand the agent waits for a project nobody has time to run, so the field dictionary starts with the fields your first job reads and grows one job at a time.
  • In HubSpot, a Customer is a company with at least one closed deal, and HubSpot's automatic updates only move that stage forward. So a client who left two years ago is still a Customer unless someone changed it by hand. Ask an agent to draft a renewal note to every current client, and it can pick them by that stage and write to former clients too. Who counts as a current client is something your team knows, for example an open project in Asana or a repeating invoice in Xero, and the field dictionary writes that down once for every agent.
  • Keep one master copy of the field dictionary, because an agent answers from whatever copy it reads, even an old one. Some agents can read the master directly, such as Claude Code reading it from your GitHub repo. Others need their own copy, such as the file you upload to a Claude Project. Those copies have to be updated the same day the master changes.
  • A quick check is to ask the agent the test questions that come with your field dictionary, for example "Does a deal in Contract sent count toward this month's forecast?" Then compare its answers with the expected ones. If they don't match, the agent isn't reading it, and its forecasts still rest on guesses.

Why does an agent get your CRM wrong when the data looks fine?

The connector between your CRM and Claude or any other agent passes the value across, such as contractsent for a deal stage or Amber in a custom field called Deal health. The meaning your team gave that value never travels with it.

With a default field like Deal stage, the agent at least falls back on HubSpot's meaning, even when your team uses the field differently. Fields your team added yourselves are harder, because the CRM has no default meaning for them at all.

Say your team uses a dropdown called Deal health, where Amber means the buyer has gone quiet for two weeks. The agent only sees the word Amber, guesses it means a small risk and keeps the deal in this month's forecast.

Salesforce recommends that admins fill in each field's Description, because Agentforce uses it as context to make decisions. An empty Description leaves the agent guessing.

Gartner predicted in May 2026 that companies that write down what their data means will raise the accuracy of their AI agents by up to 80% by 2027. The advice was aimed at the data leaders of large companies.

We tested this ourselves in a HubSpot test account with 24 made-up deals, asking which deals will close this month. Without a field dictionary, the agent added up HubSpot's weighted amounts, reported €113,100 for the month and flagged nothing. With one, it reported €24,000 as Commit and €81,000 as Best case. It also flagged a deal whose stage nothing on the record backed, and two values the team had never defined. Claude, Claude Code and the ChatGPT desktop app all gave that answer, while Codex left two deals out of Best case.

Do you have to clean the whole CRM first?

You don't, because the agent only reads the fields its job needs. Those are the only fields you have to define and check, and the rest of your CRM can stay as it is.

For the Monday forecast in HubSpot that is about eight fields: Deal stage, Close date, Amount, Deal probability, Weighted amount, Deal owner and Pipeline, plus any field your team added that changes the answer, such as Deal health.

A messy field the job never reads doesn't change the agent's answer. If your Lead source field holds LinkedIn, linkedin and LI for the same channel, the forecast is still right, because the agent never looks at Lead source. Cleaning that field first only delays the job you wanted to hand off.

Among the fields the forecast does read, check which ones reps fill in by typing instead of picking from a list. Say your team has a text field called Contract length. The agent will read 12 months and 1 yr the same way without help.

But when a rep types annual, it can't tell a one-year contract from a three-year contract billed once a year. And 2+1 means nothing to it until someone writes down that your team uses it for two years with an optional third.

Changing that field inside the CRM is a bigger job than it looks. HubSpot's property guide says some default fields, and any field a workflow or segment already uses, can't be edited. So leave that to your CRM admin as a separate piece of work.

The field dictionary doesn't have to wait for it. It can list the values your team already types and say what each one means, for example that annual means billed once a year and 2+1 means two years with an optional third. It also tells the agent to flag any value it doesn't recognize instead of guessing.

What goes in the field dictionary?

Each field the job reads gets one entry with six parts, and together they answer the questions an agent would otherwise guess at:

  1. The field, written as the tool, the label your team uses and the internal name, such as HubSpot's Deal stage with the internal name dealstage, because that's the name the connector hands the agent.
  2. What the field means in your team, in one or two sentences, including what it doesn't mean.
  3. The values the field allows and what each one means.
  4. The source of truth, meaning which tool to trust when two tools hold the same figure, and from when.
  5. Who may change it, which is a named role, read only, or a rule that the agent proposes and a person approves.
  6. One real example value.

Here are three entries for Acme Corp, a made-up services firm. The rows are illustrative.

FieldWhat it means at Acme CorpAllowed valuesSource of truthWho may change itExample
Xero invoice StatusAUTHORISED means approved and sent but not fully paid, and it also covers invoices that are only partly paidDRAFT, SUBMITTED, AUTHORISED, PAID, VOIDED, DELETEDXeroFinance only; read only for agentsAUTHORISED
Asana project statuscomplete means our delivery team has finished; it does not mean the client has signed offon_track, at_risk, off_track, on_hold, complete, droppedAsana for delivery; HubSpot for the client's sign-offWhoever schedules deliverycomplete
HubSpot custom field Renewal dateThe last day the client can give notice, not the day the contract endsA dateHubSpotAccount manager; agent proposes2027-03-31

Each of these reads like plain English and means something narrower. An agent asked which invoices are still open can't tell from the status alone, because Xero gives AUTHORISED to unpaid and partly paid invoices alike.

An agent told to raise the final invoice when a project turns complete bills the client before they've signed off. And one that reads Renewal date as the contract's end books the renewal call after the client could already have cancelled.

Deal stages need more than a meaning. A stage name usually says what your team did, and the agent needs to know what the buyer did.

So each stage entry also says what has to be true to enter it and to leave it. For example, a deal enters Contract sent when the order form is with the buyer and leaves when the buyer's legal team replies. The agent can check that on the record, because the order form is attached to the deal. The entry also says whether that stage counts toward commit or only toward best case. In the kit's template, Contract sent counts toward commit only once the buyer names a signing date in writing.

The kit's template has sample rows for nine fields and seven deal stages. It also has eight rules the agent follows on every run, such as reporting an empty field as empty instead of guessing.

How do you write the first version in a day?

You let Claude do the reading and drafting, and you spend your time on the answers only your team has. So block time in your calendar for the interview, with no meetings or chat. Some answers sit with colleagues, so ask them first, or mark those fields as open and fill them in later. These are the five steps:

  1. Pick one job and write it down in one sentence, for example "every Monday, list the deals likely to close this month and what's blocking each one".
  2. Let Claude find the fields that job uses. Set your CRM connector's write tools to Needs approval first. Then open a new Claude chat and paste the prompt from our kit. Claude lists those fields, what each one is called inside the CRM, which options it allows and how often it's left empty. It only reads and never shows you names or emails, and if your CRM isn't connected, it asks you to paste the field list instead.
  3. Check each meaning with the colleague who enters that data. Claude drafts an entry for every field, marks the parts it guessed and asks you one question per field. Some answers only the person typing the value knows. Your sales reps know whether a close date is the buyer's date or their own target, and whoever sends your invoices knows from when the billing tool, not the CRM, holds the right amount.
  4. Test the field dictionary before anyone relies on it. Open a new chat and ask the agent the test questions the interview wrote for your fields, for example "Which amount goes on the first invoice for a two-year deal?" Then compare each answer with the expected one. If they differ, the agent isn't using your definitions yet.
  5. Put a date and an owner at the top and save it where your agents will read it, which the section after the worked example covers.

The kit also has a skill called crm-field-dictionary. A skill is a folder of instructions an agent loads when a task needs it. This one tells the agent to read the field dictionary before any task on deals, invoices or renewals. It can also run the interview for you and check the field dictionary against your tools. It only reads and never edits the field dictionary or your CRM. You upload it in Claude and in ChatGPT's desktop app, and install it as a plugin in Claude Code and Codex.

A worked example: one closed deal, three tools

When a deal at Acme Corp moves to Closed won in HubSpot, the agent opens the project in Asana and drafts the first invoice in Xero. Three entries in the field dictionary decide whether that goes right. Acme Corp and its rules are illustrative.

The first entry says what Closed won means. At Acme Corp a deal only counts as won once the signed order form is attached to it, so the agent looks for that file before it does anything else. Without the entry, a deal a rep moved on a verbal yes gets a project and an invoice the client never agreed to.

The second says who gets the invoice. At Acme Corp the invoice goes to the legal entity named on the signed order form, and that is often not the company name in HubSpot, for example when a client's parent company pays. So the agent takes the billing name from the order form and looks for it in Xero's contacts before it creates a new one. Without the entry, the agent bills the name in HubSpot, and the client's finance team sends the invoice back.

The third says who may change what. The agent may save the invoice in Xero as a draft, but only the person who handles invoicing approves and sends it. Only the person who schedules the delivery team sets the start date in Asana. Without the entry, the agent has no rule that tells it to wait, so it could send the invoice to the client itself.

Three entries decide whether the closed-deal handoff goes right When a deal at Acme Corp, a made-up services firm, moves to Closed won in HubSpot, the agent reads the field dictionary before it acts, then opens the project in Asana and saves the first invoice in Xero as a draft. Three field dictionary entries decide whether that goes right. Entry 1: Closed won means the signed order form is attached to the deal. Entry 2: the invoice goes to the legal entity named on the signed order form. Entry 3: the agent saves drafts; a person sends the invoice and sets the start date. CLOSED-DEAL HANDOFF AT ACME CORP (ILLUSTRATIVE) HubSpot deal 01 Stage moves to Closed won Signed order form attached Agent Reads the dictionary before it acts Asana 03 Opens the project Start date set by a person Xero 02 · 03 Bills the order-form entity Draft only; a person sends 01 Closed won means the signed order form is attached 02 The invoice goes to the legal entity named on the signed order form 03 The agent saves drafts; a person sends the invoice and sets the start date
Three entries decide whether the closed-deal handoff goes right When a deal at Acme Corp, a made-up services firm, moves to Closed won in HubSpot, the agent reads the field dictionary before it acts, then opens the project in Asana and saves the first invoice in Xero as a draft. Three field dictionary entries decide whether that goes right. Entry 1: Closed won means the signed order form is attached to the deal. Entry 2: the invoice goes to the legal entity named on the signed order form. Entry 3: the agent saves drafts; a person sends the invoice and sets the start date. CLOSED-DEAL HANDOFF (ILLUSTRATIVE) HubSpot deal 01 Stage: Closed won Agent Reads the dictionary Asana 03 Opens the project Xero 02 · 03 Drafts the invoice 01 Closed won means the signed order form is attached 02 The invoice goes to the legal entity named on the signed order form 03 The agent saves drafts; a person sends the invoice and sets the start date
Fig. 1 — Closed-deal handoff at Acme Corp (illustrative) · 3 field dictionary entries

The agent does the work across all three tools, and a person signs off on the two steps the client and the delivery team will see. This handoff is a job you build on top of the field dictionary, because the kit's skill only reads.

Where should the field dictionary live so every agent reads it?

Keep the master copy where your team already works. For most teams that's a shared Google Drive or Notion folder. If someone on the team already uses Claude Code or Codex, a GitHub repo works too, because every change then goes through a pull request and gets dated. The kit's repo is a GitHub template, so you can copy it into a private repo of your own. It already holds the CLAUDE.md and AGENTS.md files that tell Claude Code and Codex to read the field dictionary.

Then connect each agent to the master copy in the way that agent supports. Some agents can read it directly, and others need a copy that someone updates by hand. Breeze, for example, can read Google Drive and Notion but not GitHub.

Where your agent runsHow it gets the field dictionaryMaster or copy
A shared Claude ProjectUpload the file to the project's knowledge. Then add one line to the project instructions: read the field dictionary before answering anything about deals. On Team and Enterprise plans you can share the project with your team (Claude Projects help).Copy
A Claude skillAn owner on a Team or Enterprise plan can provision the kit's skill for every user. Claude uses it when a request matches the skill's description (Claude Skills help).Holds the steps, and reads the field dictionary from the Project or repo
Claude CodeClaude Code reads the project's CLAUDE.md file at the start of every session. The file reaches the team through version control (Claude Code docs).Master if you keep it in GitHub; otherwise a copy
CodexCodex reads the repository's AGENTS.md file at the start of a session. The file reaches the team through version control (Codex docs).Master if you keep it in GitHub; otherwise a copy
A ChatGPT ProjectAdd the same file to the project's sources, and the same line to its instructions.Copy
HubSpot BreezeConnect Google Drive or Notion to the agent through Breeze's MCP client, or upload the file to a knowledge vault.Master through Drive or Notion; copy in a vault
Salesforce AgentforceYour admin pastes each field's meaning into that field's Description in Salesforce.Copy, one field at a time

We tested the Claude Project, Claude Code and Codex setups on 17 November 2026, and the skill in ChatGPT's desktop app. We haven't tested the ChatGPT Project, Breeze or Agentforce rows yet. Those steps come from each vendor's own help pages, which we checked on 15 November 2026.

If your team changes what Contract sent means, you update the master copy. But the file in your Claude Project and the Descriptions in Salesforce still hold the old meaning, so the agents reading them keep using it.

Keep a list of every place that holds a copy and update them all on the same day. Then ask the test question from step 4 in each place, so you know none was missed.

Who keeps it current?

Name one person as the owner, usually whoever runs operations. The field dictionary needs an update whenever something changes in one of your tools, not on a fixed schedule.

When someone adds a deal stage or a new dropdown option, they update the field dictionary that same day. The agent sees the new value the next time it runs, and without an entry it has no meaning for it.

Agents can spot what's missing, but a person decides what goes in. If an agent finds a value it doesn't know, such as a new Deal health option called Grey, it suggests an entry, and the owner approves it or writes the right meaning.

If agents added entries themselves, one wrong guess would become the meaning every agent reads.

The skill's check mode compares the field dictionary with the fields in your tools and lists anything added, renamed or removed. Running it once a quarter catches the changes nobody told the owner about.

What won't the field dictionary fix?

It won't fill in missing data. If reps leave Close date empty, the field dictionary makes the agent report the gap instead of guessing a date, but someone still has to enter it.

It won't change how your team works either. If deals move to Contract sent before legal has seen anything, writing that down makes the forecast honest, and the deals still take as long to sign.

It also won't help with a job you haven't written it for. Say you start with the Monday forecast and later ask the agent to chase overdue invoices. It then reads Xero fields the field dictionary doesn't cover yet, so add those fields before you hand it the new job.

FAQ

Is a field dictionary the same as a data dictionary?

It's a smaller one with a different reader. A data dictionary is usually written for the people who build reports, so it lists every field.

A field dictionary is written for an agent. It covers only the fields your agents' jobs read and adds two things an agent can't work out on its own: which tool to trust when two disagree, and who may change each field.

Should the agent write the definitions for us?

It can draft them, and the kit's prompt has Claude do that from your field settings. But someone on your team has to confirm each one. Claude can tell you that a field called Renewal date holds a date, but only your account managers know it's the last day a client can give notice.

What if two teams use the same field differently?

Sales might use Close date for the day the buyer signs, while finance reads it as the day the first invoice goes out. Agree on one meaning and write it down before any agent reads the field. If both teams really need their own date, that's two fields, and adding the second one is a job for your CRM admin.

Do we need a developer to set this up?

Not to start. A Claude Project, a shared skill and Breeze reading from Google Drive or Notion all work without one. Keeping the master copy in GitHub for Claude Code or Codex needs someone who works with Git, and copying meanings into Salesforce Descriptions needs whoever runs your Salesforce.

Where ProNova comes in

We connect the tools your team already uses, such as HubSpot, Asana and Xero, to coding agents like Claude. If your CRM already has its own AI agent, we build the steps it doesn't reach in your other tools.

Our AI Workflow Lab is the place to start if your team doesn't trust what its agents say about your own data yet. The same goes for a job like the closed-deal handoff, where someone keeps switching between your CRM, project tool and billing tool. In the Lab, we go through that work with your team.

The field dictionary is yours to write either way. If you want to talk through which job to start with, book a free 30-minute workflow scoping call.

Topics
Author
Izzy Aly · Co-Founder, Systems and Architecture
Share

Work with us

Got more workflows than time to fix them?

The AI Workflow Lab maps where AI fits across your CRM and the tools around it, and tells you what to build first and what each build will cost.

or book a scoping call (opens Google Calendar)