Agent Cal’s Codex 

Agent Cal can answer questions about your data—but only if it has a clear map of what everything means and how it connects (the schema). This guide shows you how to build that map for tables outside of what Agent Cal sees by default.

Tables and Columns

Think of a table like a spreadsheet tab, and columns as the headers across the top. When you describe a table for Agent Cal, each column needs three things: a name, a data type, and a plain-English description. The description should be as short as possible while still providing essential information to Agent Cal. 

Formatting your data map (schema)

Format:

column_name(type):Description of what this column means.;

Example:

campaign_cost(f):The total money spent on this campaign. Also called spend or budget used.;

The letter in parentheses tells the AI what kind of data it’s dealing with:

Code	Means	Example
s	Text	Names, IDs
i	Integer, (A whole number)	Counts
f	Decimal number	Costs, percentages
b	True / False	Fields whose values can only by “True” or “False”
d	Date	2026-02-20
ts	Date + Time (Timestamp)	2026-02-20 15:37:49 UTC
n	Precise number	Exact financial figures

💡 Your description is the most valuable part. The more context and synonyms you include, the smarter the AI’s answers will be.

---

Some Tables Have Strict Rules

Certain tables can produce wrong answers if used carelessly. You can attach a mandatory warning to any table using !> — think of it as a sticky note the AI must always read before touching that table.

Example: !> Always filter by attribution model before using this table.

---

Joins – How Tables Connect

If two tables share related data — like a Campaigns table and an event table — then Agent Cal needs explicit instructions on how to link them. For each connection, provide on its own line:

• Which two tables are connecting and which columns link them together
• Why they connect (in plain English)
• How to connect them — choose one of three options:

Types of Joins

There are two primary joins that you should use:

LEFT: Includes everything from table 1, even without a match from table 2 — use when you always want all records from one table, even if the other has nothing to add.

INNER: Only include records that match table 1 AND table 2 — use when data is only meaningful if both tables have a corresponding entry.

Connect a table to itself — used for hierarchies, like linking a company to its parent company within the same table. Can be a left or inner join

Format:

Table 1, Table 1 Key, Table 2, Table 2 Key, Type, Purpose Logic (why)

Example:

cm.cm_insights_attribution, member_id, cm_eventstats, id, inner, cm_eventstats contains additional information about each event not found on cm_insights_attribution. All events on cm_insights_attribution MUST be on cm_eventstats

---

Quick Checklist for Adding Custom Data

• [ ] Table name (your admin can help with formatting)
• [ ] All column names with plain-English descriptions and data types you want Agent Cal to have access to
• [ ] Any mandatory rules the AI must follow for this table
• [ ] How this table connects to existing tables, and why