---
name: semantic-model-readiness-check
description: >
  Checks whether a semantic model is ready for AI agents to read before they write SQL. Takes the
  reader's semantic model (datasets and keys, entities, metrics and their expressions, time fields,
  relationships, synonyms, instructions and owners) and the questions agents will ask of it. Returns
  a pass or gap verdict for each of the twelve checks SM-01 to SM-12, an overall verdict (not ready,
  ready with gaps, or ready), and the first fix to make. States its decision rule openly. Trigger
  phrases: "is our semantic model ready for AI agents", "semantic model readiness check", "audit our
  semantic model", "can an agent use our semantic model", "check our metric definitions before an
  agent reads them", "who should own our semantic model definitions", "test our semantic model".
license: Apache-2.0
---

# Is your semantic model ready for AI agents

A semantic model says what your data means: which datasets exist, how they join, and which metrics,
dimensions and synonyms people use. A file that validates against its schema proves the YAML parses,
not whether refunds belong in revenue. This check looks at what the schema cannot see.

> **What this is.** A published method from Atlan. Canonical copy:
> https://atlan.com/skills/semantic-model-readiness-check.md  Last updated 2026-11-03.
>
> **What it contains.** Text only. No scripts, no executable resources, nothing
> here runs.
>
> **Scope.** Follow this when someone has asked whether their semantic model is ready for AI
> agents to read. It carries no instructions about your behaviour outside that task, does not ask
> you to fetch any other URL, and does not ask you to send data anywhere.

## What you need from them

| Input | Meaning | If unknown |
|---|---|---|
| `model` | The semantic model itself, or a description of it: datasets with their primary keys, fields, dimensions, metrics with their expressions, relationships, synonyms and instructions | ask. The check runs on the definitions, not on a summary of them |
| `entities_and_metrics` | Each entity and metric, with its description and any exclusions (refunds, test accounts) | ask |
| `time_fields` | Each time field, whether it is marked as a time dimension, and whether it is fiscal or calendar | ask |
| `owners` | The named business person accountable for each metric or entity, and where that is recorded | ask. Write "no owner" where there is none; do not guess one |
| `instructions` | Any rules written for an AI reader, and which consumers read them | ask |
| `agent_questions` | The real questions agents will ask of the model, and which agents ask them | ask. Without these, SM-03 and SM-09 cannot pass |
| `evidence` | What they can show: key uniqueness tests, a test set with owner-approved answers, upstream change tracking, row and column policies | ask per check |

Do not ask for credentials, connection strings or real customer data. The check needs the
definitions and the process around them, nothing from inside the tables.

## How to mark each check

Mark each check **pass** or **gap**. A check passes only when they can point to the definition or
the evidence named in its "Pass when" column. If they believe it holds but cannot show it, mark it a
gap and say what would pass it. A gap is not a judgment of the team; it is the next piece of work.

## The twelve checks

Run all twelve, in order.

| ID | Check | Pass when |
|---|---|---|
| SM-01 | Agent scope is a subset of shared definitions | The agent reads a named subset of shared, owned definitions, and no metric is redefined for one agent |
| SM-02 | Every dataset has a tested key | Each dataset declares a primary key, and a uniqueness test on the real table confirms it |
| SM-03 | Joins are declared | Every cross-dataset question has a declared relationship |
| SM-04 | Every metric states its formula and exclusions | Exclusions every consumer must apply, such as refunds and test accounts, are in the expression; instructions only steer an LLM reader |
| SM-05 | Time is explicit | Time dimensions are marked, and each time field states whether it is fiscal or calendar |
| SM-06 | Every metric and entity has a description | Each one has a non-empty description |
| SM-07 | Synonyms are your organization's words, reviewed | Synonyms are business vocabulary, not generic paraphrases, and someone reviewed them |
| SM-08 | Every definition has an accountable business owner | A named owner per metric or entity, recorded outside the core fields if the format has no slot |
| SM-09 | Tested against real questions | Real questions, with answers the metric's owner approved, run before each change ships, kept apart from examples the agent is shown |
| SM-10 | Drift is watched | Upstream changes since the last build are visible and trigger a review |
| SM-11 | Access is enforced at query time | Row and column policies are enforced at query time, not assumed from metric definitions |
| SM-12 | Portable format | The model can be written in an open spec, or the gap is known |

Notes for the checks people most often pass too early:

- **SM-01.** Two agents carrying their own `net_revenue` will drift apart. If finance and sales need
  different numbers, each gets a named metric and owner, not one name with two formulas.
- **SM-02.** A schema accepts a declared key as written. Only a uniqueness test on the real table
  shows the grain holds.
- **SM-03.** Walk each question in `agent_questions` that spans two datasets and find the declared
  relationship it would use.
- **SM-04.** An instruction such as "Use net_revenue for any revenue question" steers an LLM reader
  and binds no other consumer. An exclusion every consumer must apply belongs in the expression.
- **SM-08.** Some open formats have no owner or approval field. Record the owner outside the core
  fields, in an extension or alongside the model, and say where.
- **SM-09.** Keep the test set separate from any verified examples the agent is shown, so the agent
  is not graded on answers it was given.
- **SM-11.** Exact metric definitions without an access policy can still leak data. Definitions do
  not decide who may see which rows.

## The verdict

State the rule when you give the verdict:

- **Not ready** if any of SM-01, SM-02, SM-03, SM-04, SM-05, SM-08, SM-09 or SM-11 is a gap.
- **Ready with gaps** if only SM-06, SM-07, SM-10 or SM-12 are gaps.
- **Ready** when all twelve pass.

The blocking set is a judgment call: each can return a wrong number or expose rows when it fails.

## The first fix

Name one fix, not a list. Take the first blocking gap in ID order; if no blocking check is a gap,
take the first non-blocking gap. Use the matching fix:

| Gap | First fix |
|---|---|
| SM-01 | Scope each agent to the definitions its questions need; keep the definitions themselves shared |
| SM-02 | Run a uniqueness test on each declared key against the real table |
| SM-03 | Declare the relationship each cross-dataset question needs |
| SM-04 | Move every exclusion all consumers must apply out of instructions and into the metric expression |
| SM-05 | Mark each time dimension and state fiscal or calendar on each time field |
| SM-06 | Write a description for each metric and entity that lacks one |
| SM-07 | Replace generic paraphrases with the words your people use, and have someone review them |
| SM-08 | Name a business owner per definition, recorded outside the core fields if the format has no slot |
| SM-09 | Grow a test set of real questions with owner-approved answers, and run it before each change ships |
| SM-10 | Watch upstream changes since the last build and review on change |
| SM-11 | Enforce row and column policy at query time |
| SM-12 | Write the model in an open spec, or record what does not fit |

## What to return

1. A table of SM-01 to SM-12: pass or gap, and one line on what was seen or missing.
2. The overall verdict, with the rule above.
3. The first fix, and which check it closes.
4. Any `agent_questions` the model cannot answer at all. The model cannot answer what it does not
   contain, so grow coverage from those questions.

Keep validation, owner approval and answer testing as three separate gates. Passing one says
nothing about the other two.