There are three things an agent can know about a field. To date, symantic layers have focused on capturing the first two.
What it’s called. Synonyms. amt_ttl_pre_dsc is “gross revenue,” also “total before discount,” also “pre-discount amount.” Databricks lets you attach ten of these per field. Snowflake semantic views carry them. They help a model match a user’s words to a column.
What it means. Descriptions. “Gross revenue before discounts, in the opportunity’s currency, as of the last stage change.” Everyone has these. Salesforce has one per field, visible to agents through the schema.
How to use it. This is the third level, and it’s the one that changes answers.
Health score below 60 warrants outreach. Sourced from the CS platform, refreshed nightly. Internal only — never quote to a customer.
That isn’t a synonym or a description. It’s a directive. It tells the agent what the value implies, where it came from, how fresh it is, and what it must not do with it. In linguistics the distinction is semantics versus pragmatics: meaning in isolation versus meaning in use. We’ve taken to calling the third level pragmatics, because nothing else in the vocabulary names it.
The missing third level
We looked hard at this, because in our initial AI development the pragmatics were critical to building features “that worked every time”.
Databricks’ agent metadata is synonyms, display names, and formats. Snowflake has descriptions at every level, verified query pairs, and custom instructions — but the instructions attach to the view, not the field, and they describe how to generate SQL, not how to weigh a value. dbt and Cube carry descriptions and governance rules. Salesforce surfaces the field Description to agents, which validates the idea — but a field has exactly one Description, it’s global, and editing it requires Customize Application, so it’s an admin change with a release behind it.
None of these can say: this field means something different to Finance than it does to Sales. None can say: in a renewals context, weigh this; in a pipeline context, ignore it. None can say: don’t quote this to a customer.
The institutional knowledge that is seldom written down
Every org has a layer of field-level knowledge that lives in people’s heads. It’s the stuff you learn in your second month:
- The renewal date is a day behind. It syncs overnight from the CS platform. Don’t tell a customer their renewal is tomorrow when it’s today.
- “Partner” means reseller here. Not referral partner. Not technology partner. The picklist label is a historical accident.
- Stage 3 without a mutual close plan isn’t real pipeline. Everyone on the sales floor knows it. The stage field doesn’t.
- Close Date on Stage 1 deals is a placeholder. Reps put the end of the quarter. Never forecast from it.
- Health score below 60 warrants outreach. Below 40, escalate. The number doesn’t come with the thresholds.
- The Amount field before the 2023 migration is unreliable. Anything with a created date before March 2023 was converted at a flat rate.
Legacy_Sync_ID_DO_NOT_USE__c. The name says it. The agent reads the value anyway.- Discount percentage is internal. It appears on the record. It never appears in anything a customer sees.
- Last Activity Date excludes automated emails. So a deal can look dead when the sequence is running.
- “Open” on Opportunities means these four stages, not “not closed.” Ask five people and you’ll get three definitions. The agent should get one.
Not one of these is a synonym or a description. Every one of them changes what a correct answer looks like. And today, in most orgs, the only place they exist is distributed across the team.
Why they belong on the field, not in the prompt
The usual workaround is to write these into an agent’s instructions. It works until you have two agents.
Instructions in a prompt are per-surface. The Agentforce topic has one version. The Claude project has another. The Flow has none. When the renewal sync changes to twice daily, one of them gets updated.
A pragmatic instruction attached to the field rides with the value every time the value is delivered, to every surface, from one definition. Change it once. And because ContextWorks attaches instructions per entity and per domain, the same amount field can carry Finance’s reading in the Finance domain and Sales’ reading in the Pipeline domain — which is how business meaning actually works. It’s audience-dependent, and one global string per field structurally cannot be.
Who writes them
The honest objection to all of this: someone has to write it down, and that person is super busy.
Three answers. First, the people who hold this knowledge aren’t data engineers; they’re RevOps, sales ops, CS ops — and ContextWorks is built for them to author directly, by configuration, no developer. Second, you don’t need all ten on day one. Start with one object and the five instructions that would have prevented the last wrong answer. Third, the alternative isn’t “no one writes it down.” It’s “it gets written into three prompts by three people and drifts.”
The industry is converging on the view that agent context is a discipline — dbt now talks about the “context engineer,” and large Salesforce customers have stood up teams with that name. The thing those teams are collecting, mostly, is pragmatics. It’s worth having a place to centralize, manage and distribute them - and that place is ContextWorks.
