Instructions
Instructions attach business meaning to context — the definitions, thresholds, and cautions an agent needs to read your data correctly. They are one slot of the Meaning editor, alongside a label and synonyms. → Semantics
Where they live
Look for the same glyph at every scope. It is filled when something is declared and bare when nothing is.
| Scope | Where | Applies |
|---|---|---|
| Entity | Builder → Meaning | Every load of this entity |
| Domain | Domains → edit → Meaning | Every catalog that domain scopes |
| Field | Field picker → Meaning column | Rendered inline with the value |
| Element | The element’s Details tab | Rendered with the metric or formula |
All of them travel with the data, in both markdown and JSON.
Instruction or prompt?
If it’s about your data, it’s an instruction. If it’s about the agent’s job, it’s a prompt. “Health score below 60 warrants outreach” is data; “answer in three bullets” is the agent’s job.
An instruction is written once and arrives with every agent and surface that receives the data. A prompt has to be copied and kept current per agent — it goes stale invisibly.
Entity instructions
Org guidance the agent receives on every load of this entity. Write it as guidance to a capable new hire:
Accounts here are paying customers only — prospects live in Leads. Treat an account with no open opportunity and a renewal inside 90 days as at risk regardless of health score. Never quote a renewal date to a customer without checking the contract record.
Include: what this object means at your company, rules that span fields, cautions, and what the entity doesn’t cover. Leave out: restating what fields already say, formatting rules (“use bullets” belongs in the prompt), and anything about a single field — put that on the field.
Field instructions
Rendered inline with the value:
- **Health Score:** 72 — _0–100, refreshed nightly. Below 60 warrants outreach._The test: would a smart new hire misread this value? If yes, write an instruction.
| Field | Instruction |
|---|---|
Health_Score__c | 0–100, refreshed nightly. Below 60 warrants outreach; below 40 is escalation. |
Type | ”Partner” here means a reseller, not a technology partner. |
Amount | Gross, before discount. Net is Expected Revenue. |
Stage | Stages 4+ require a signed order form. Stage names are legacy; 3 is “Proposal”. |
Owner | The account owner, not the deal owner. Deal ownership can differ. |
Don’t annotate the obvious — Name needs nothing, and an instruction on every field dilutes the ones that matter.
Open the Meaning editor on a field row and you can also rename it for the agent and list what people call it. → Fields
Domain instructions
What a domain covers, in your terms. It leads the catalog every scoped tool receives, before any entity:
Finance reads the same records as Sales, in contract terms. Booked value, not forecast.
Use it where two teams read the same objects differently — it is the one place to say so once.
Element instructions
A number without its definition is ambiguous: “Open Pipeline: $40,000” invites follow-up questions; with an instruction it invites none.
| Metric | Instruction |
|---|---|
| Open Pipeline | Open, unweighted, excludes closed-lost. |
| Open Cases | Open service cases: a signal of active support load. |
| Deals Won (12 mo) | Rolling 12 months from today, not fiscal year to date. |
The instruction lives on the element, so every entity using it gets the same definition.
Best practices
- Be specific and falsifiable. “Below 60 warrants outreach” beats “important metric”.
- Say what to do, not just what it is. Thresholds, actions, and cautions beat definitions.
- Keep them to one or two sentences. They cost tokens on every load.
- Write for someone who doesn’t know your org.
- Flag unreliable data. “Populated by an integration that lags about a day; treat as approximate.” An agent that knows a value is approximate hedges; one that doesn’t states it as fact.
If you’re economizing on tokens, cut low-value fields first — they cost tokens too and carry no meaning.