Metadata is what makes a model usable without you in the room. A description tells a person what a field is. AI context tells an agent how to use it, and what not to do. A format tells every table and chart how to show it. In Kater all three sit beside the field’s definition, so they change together, and the Shared models editor lets you fill them in like a spreadsheet.

Where context lives

An agent reads context from several places, from the whole organisation down to one field. Put each fact at the narrowest level where it is true.

Edit metadata in the editor

Open the model in Shared models. Every edit writes the directive or frontmatter key for you, saves itself, and undoes exactly.

Fields, many at once

Select Fields above the grid. The Fields sheet has a row per field, with its Description, Format, Values and AI context. Click a cell to edit it, or paste a whole column at once: it saves as one change. A field whose label is still its SQL name says No label.

Write labels or descriptions with Ask

The sheet’s header counts what is missing, such as “60 fields, 21 with no label” or “42 fields, none described”. Write labels with Ask or Write descriptions with Ask opens Ask with a prompt for your agent that lists those fields. Your agent writes them through the same operations, and you review them in the sheet.

One field

Click a field to open its panel: Label, Description, AI context, Format, Values, Tags and Business questions. The field menu also has Format and Values. See Fields.

The model

Select Details on the toolbar. The panel holds the model’s Label, Description and AI context, its Business questions and Tags, each with Add, and Always filtered: the filters with fixed values that apply to every reader. Show as YAML shows the frontmatter as the file has it.

A join

Click a join’s chip in the diagram. Its panel ends with About this join: Label, Description and AI context. See Relationships and joins.

Field directives

1
  -- @description Sum of platform-reported attributed conversion value using upstream definitions and attribution.
2
  -- @format currency(union__currency, 2)
3
  -- @ai_context Uses each advertising platform's reported conversion value and attribution. Values are combined without cross-platform deduplication or currency conversion.
4
  MEASURE('sum__conversions_value', SUM(base.conversions_value), NOT_ADDITIVE_ACROSS(union__currency)) AS "Conversion Value"

1
  -- @description Earliest event_date_dt for the row. It is a dimension, not a measure to aggregate.
2
  -- @business_questions "When did each client first show up?" "How many new clients arrived per day?"
3
  -- @tags "acquisition"
4
  DIMENSION('first_seen_start_date', sessions.session_start_date) AS "First Seen Start Date",

Write directives on the lines directly above the field. A trailing /* @format currency(currency, 2) */ after the field works too.

Formats

A format changes how a value shows, and nothing else: never the value, its grouping or its definition. Result tables, charts and definition cards use it.

Operations write a format when they add a field: percent(1) for a share of total or a percent change, number(0) for a count or a rank, plain for a date part such as a year, and the source field’s format for a sum or a running total. A pass-through or an EVAL of a field keeps its format. In the editor, a field with no format of its own says Automatic.

Model metadata

1
---
2
name: marketing_sessions
3
model_type: semantic
4
label: Marketing Sessions
5
description: One row per GA4 session with acquisition, landing, device, geography, lifecycle identity, first-seen cohort, and matched paid-media context, for lifecycle marketing questions.
6
ai_context: Select from this model alone for lifecycle marketing questions; it joins the session dimension, the lifecycle identity, and daily paid media on every query. Grain is one row per session, client key, and stream, so every count is a session count unless the field says identity or lifetime. ...
7
business_questions:
8
- Which channels and campaigns bring sessions that engage, and how does that change month to month?
9
- What does a session cost per campaign, and which paid campaigns send traffic that does not engage?
10
tags:
11
  topic:
12
  - Marketing/Sessions
13
  team:
14
  - marketing/lifecycle
15
  - sales
16
  source_data:
17
  - ga4
18
---

• Model tags are a map. Each key holds a list. Suggested keys are team, source_data, topic and curated. A slash path such as marketing/lifecycle sits under marketing when you select by tag, as in kater test --select tag:team=marketing.
• Field tags are a plain list. -- @tags "acquisition" has no keys.
• Tags never grant anything. They do not set ownership or verification.

How metadata carries through

Seven keys carry through a direct reference to a field: label, description, AI context, business questions, tags, classification and format. A pass-through, a plain EVAL, an alias or a cast keeps them. A directive in the reading model overrides one key at a time. A calculation over a field, such as EVAL(a) / EVAL(b), keeps only the metadata written on it.

Where to edit each kind

Write context that helps

1. State the grain. “Daily ad grain within source_relation, platform, account, campaign, and ad group.” An agent then groups at the right level.
2. Say what not to combine. “Other shared ad reports are overlapping rollups; do not add their totals to this model’s totals.”
3. Put a caveat where it applies. A join’s matching gap goes in the AI context of that join, not in the model’s frontmatter.
4. Write business questions as people ask them. Agents search them, and the Tests tab and kater test generate --from-questions turn them into tests.
5. Format every number. A format stops a currency from showing as a bare decimal, and an ID from showing with separators.

Agents search labels, descriptions, tags and business questions through the MCP’s catalog search, so plain words here make fields easier to find.

Common errors