References
A reference embeds a parent record inline, curated by the parent’s own entity. Related lists go down to children; references go up to parents.
Add one
In the entity builder, click + Add Referenced Object under Referenced Objects.
| Setting | What it does |
|---|---|
| Lookup Field | Which lookup on this object to follow — AccountId, OwnerId, a custom lookup |
| Label | What the agent calls the embedded block |
| Embed Level | Which level of the parent’s entity to render |
References render at detailed only, like related lists — an embedded record is a second record’s worth of context.
What it produces
On an Opportunity entity, a reference on AccountId at standard gives the agent the Account’s curated standard-level fields inline, under a labeled block — not the ID, not just the name. The parent renders through its own entity, so the Account block is curated once and appears consistently wherever it’s referenced.
When the lookup is empty, the block still appears and says so — markdown renders None linked., JSON carries missing: true. The agent learns there is no parent, rather than wondering whether one went unfetched. → Payloads
Choose the embed level
| Level | When |
|---|---|
list | You need identity and a couple of qualifiers. The usual default |
standard | The parent genuinely informs decisions about the child — Account on an Opportunity |
detailed | Rarely right. This nests a full 360 inside another one |
Start at list and go up only if the preview shows you’re missing something you’d use.
Reference or a cross-object field?
| You need | Use |
|---|---|
| One or two parent fields | A field on the lookup path — Account.Industry. → Fields |
| The parent’s curated view | A reference |
A reference costs more tokens but arrives as a coherent labeled block with its own instructions, rather than loose fields in the child’s list. Three or more cross-object fields from the same parent is usually the point to switch.
Good candidates
- Account on Opportunity — you can’t reason about a deal without knowing who it’s with.
- Owner on anything — when the agent may route or attribute. The User entity’s
listcuration decides what “Owner” shows. - Parent Account on Account — when the parent’s status affects the child’s.
- Contract or Product on a line item — where the parent carries the terms.
Poor candidates
- Chains of references. The parent’s entity may carry its own references at
detailed, so embedding atdetailedcan pull in more than you expect. Preview before committing. - Record Type, Currency, and similar lookups — usually better as a single field.
- A parent with no entity — there’s no curation to render. Give the object an entity first.
Watch the cost
A reference at standard adds roughly the parent’s standard field count to the payload, and two or three add up quickly on an entity that already carries related lists. Preview at detailed and read the token estimate; once you have traffic, Usage shows tokens per load.