What an agent sees¶
Agents never read the file directly. A tool turns it into a short card per dataset and shows the card where the agent works: in the result of a tool call, or in a brief at the start of a session. This page shows what a card looks like.
Illustrative
This card follows the line formats of the first implementation. The card's exact shape is not in the spec yet; other tools may render it differently. Counts are synthetic.
The card¶
## Rents
Quarterly asking rent per market and sector. (D)
As-of (D; values G): vendor_a 2026-09-30 (param asof) (quarterly, ~20 days after period end); vendor_b 2026-06-30 (constant) (annual).
Rows (G): 7,530.
Entities (G): 55 market_id.
Coverage (G): period_yq 2010Q1..2026Q3; 110 series by market_id x sector; 104 reach the latest period; 6 have gaps.
By sector (G): industrial 2012Q1..2026Q3, 3,410 rows, 55 market_id; office 2010Q1..2026Q3, 4,120 rows, 55 market_id.
Grain (D): one row per market_id x sector x period_yq.
**Hazards** (D)
- removed column `rent_old` (2026-10-29): use `rent`
- do not: join on market names
**Facts** (F: dated lines in oryxkb/project.yaml; 1 unreviewed, 1 decision open)
- **caution** [reviewed by data-team] office includes flex space from 2026Q2: compare office within one side of 2026Q2 only (as of 2026-10-31; columns sector)
- **info** [decision open] how to treat 2020-2021 is undecided (as of 2026-10-31). Options: exclude 2020-2021 | keep all quarters
- **info** [unreviewed] the 2026Q3 file was re-sent on 2026-11-02 (as of 2026-11-02; expires 2027-01-31)
**How to use** (D)
- compare markets (columns: rent_growth, sector): then use rent_growth within one sector; never across sectors. Pitfall: sectors differ in lease length.
**Joins** (D)
- Rents.market_id -> Markets.market_id (many to one): join on market_id, never on market names
Licence (D): CC-BY-4.0.
**Columns** (type, nulls, distinct: G; unit, description: D)
| column | type | nulls | distinct | unit | description |
|---|---|---|---|---|---|
| `market_id` | string | 0 | 55 | | market code (text) |
| `sector` | string | 0 | 2 | | property sector |
| `period_yq` | string | 0 | 67 | | calendar quarter |
| `rent` | number | 12 | 6,904 | USD, per year, sources: vendor_a | asking rent |
| `rent_growth` | number | 122 | 5,310 | decimal, sources: vendor_a | quarter-on-quarter rent growth |
| `vacancy` | number | 40 | 812 | % (percent), sources: vendor_b | vacancy rate |
How to read it¶
Each line says where it came from:
- (D) declared: copied from the file.
- (G) generated: computed from the data by the tool, so nobody types counts that go stale.
- (F) facts: dated lines from the file, with their status.
| Card line | Comes from |
|---|---|
| Purpose line | purpose |
| As-of | dates_asof: where each date comes from (D), and the value read from the data or the build (G); cadence and lag_days in brackets |
| Rows | Generated from the data |
| Entities | profile.entities: distinct values per column |
| Coverage | profile.period and profile.series (default: grain minus the period) |
| By sector | profile.coverage_by, with entities counted per value |
| Grain | grain |
| Hazards | removed_columns and do_not |
| Facts | facts, ordered by severity; the label in brackets is the status ([unreviewed] is the default proposed); retired facts are not shown |
| How to use | use_cases |
| Joins | relationships that name this dataset |
| Licence | license on the dataset, else on the project |
| Columns | type (an ODCS type), nulls and distinct from the data (G); unit and description from columns (D) |
What the agent does with it¶
The card does not give orders; it states facts. An agent that reads it can:
- quote
rent_growthas a percent at the right scale (unitdecimal); - say which release each number came from (As-of);
- see that 6 series have gaps before it computes a rolling average (Coverage);
- join to
Marketson the code, not the name (Joins); - avoid comparing office across 2026Q2 (Facts), and cite the fact id if it explains why.
The YAML behind this card is the complete file on Examples.