Remote Frog

AI agents are increasingly being asked to do real analytical work: write SQL, answer business questions, spot patterns, and navigate data models they have never seen before. And that creates a simple but uncomfortable question: if your schema is often not documented well enough for a human analyst who already knows the context… is it documented well enough for an agent stumbling upon it?

The agent produces SQL that looks perfectly fine. It runs. It may even return plausible numbers. But semantically, it can still be wrong. Maybe it does not know that a status field only allows four valid values. Maybe it treats a nullable date as “unknown” when it actually means “this event never happened.” Maybe it sees three different _id fields and has to guess which one is the real join key. None of that is really a model failure. It is a documentation failure.

So I started thinking about how to answer Is this schema ready for AI agents?

From “It’s documented” to “Agents understand it”

There are already plenty of conversations about AI readiness, but they often stay at the strategic level. Useful, yes, but not always actionable. I wanted something more operational: a way to inspect a schema and say where the gaps are and what to improve first.

For me, AI agent readiness means this: how well a schema enables an autonomous agent to understand and reason about the data without domain knowledge, without follow-up questions, and without wasting context window on uncertainty.

That translates into very practical questions. Among them:

• Can the agent work out how to join tables without guessing?
• Does it know which values are valid for a categorical field?
• Does it understand what null means in business terms, not just in database terms?
• Can it tell where the data comes from and what it is used for downstream?
• Does it know the grain of the table before it writes a query that quietly duplicates everything?

The more explicitly a schema answers those questions, the less the agent has to improvise. And you already know improvised SQL is how horror films get funded.

A rubric with five dimensions

Trying to make AI readiness measurable, I put together a scoring rubric with five dimensions and a total of 100 points. The scoring is proportional: you look at the fraction of fields or tables that meet each criterion, then multiply by the maximum score for that dimension.

Note: I did not validate the rubric against hallucination rates or a formal evaluation framework (see the evaluation frameworks appendix for that side of the story). My goal here was not to claim some universal measure of readiness. If such a thing even exists, that is a separate discussion. I was more interested in establishing a baseline I could use to compare tables within the same schema, identify documentation gaps, or check whether anything improved before and after an intervention.

So no, I am not pretending this is a general-purpose readiness meter. No incense, no oracle, just basic arithmetic that helps surface relative gaps and useful comparisons.

And the resulting scale looks like this:

Score	Rating
80–100	🟢 AI-Ready
60–79	🟡 Usable with Caveats
40–59	🟠 Needs Work
20–39	🔴 Critical Gaps
0–19	⚫ Not AI-Ready

Now let’s dissect the rubric.

1. Semantic richness (30 points)

The question: Do the annotations explicitly capture business logic?

This is the most heavily weighted dimension, for good reason. Explicit relationships and valid values are what allow AI agents to reason over your data without guessing. They also save context.

What we are looking for:

• Primary keys are all explicitly marked and unique (8 pts)
• Foreign keys with explicit columns (6 pts): declared FK annotations, not just naming conventions.
• Categorical fields with explicitly enumerated options (6 pts): finite sets of values are declared directly.
• Calculated fields with formulas (5 pts): if a field is derived, for example mrr_per_user = mrr / active_users, the formula is documented.
• Cross-references and shared definitions (5 pts): documentation inheritance to external schemas and explicit references to upstream tables.

Before:

string? status;

After:

/* Order status */
@AllowedValues(["active", "cancelled", "pending", "refunded"])
string? status;

Now, an agent writing a WHERE status = ... clause no longer has to invent anything. Same with joins:

Before:

long? customer_id;

After:

/* Customer identifier from CRM */
@ForeignKey(["crm.customers", "id"])
long? customer_id;

2. Structural documentation (25 points)

The question: Does your schema include the essential structural documentation?

What we are looking for:

• Protocol header (3 pts): format, version, and conventions declared at the top.

Example::

/**
* Database is used to store hiring ops data.
*
* Table Prefixes: Types and Data Sources:
* - ATS tables (prefixed with "ats"): Synced from YOUR_ATS to YOUR_DB via Meltano/Fivetran etc
* - Google Sheets tables (prefixed with "Gsheet"): Google Sheets backed tables 
*   ingested into our DWH with Meltano/Fivetran/Other
* - Midput tables (prefixed with "Midput"): Intermediate transformation tables used...
* - Final tables: (NO prefix) Consumer-ready final table...
*
* References:
* Jan 2026 URL of a document explaining schema
* Jan 2020 URL of a project modifying the schema
* ...
*/

• Field-level documentation (7 pts): meaningful annotations that explain what each field represents.
• Table-level documentation (8 pts): purpose, grain (what makes a row unique), and audience (who uses this table).
• Nullability declaration (2 pts): explicit nullable or required markers. In our AVDL, this is always TRUE by default.
• Null semantics (5 pts): the business meaning of null is documented for nullable fields; for example, “null means the user has never logged in.”

Before:

record OrdersSnapshot { ... }

After:

/**
 * OrdersSnapshot - Current order state by day
 *
 * Source: Derived from order events and billing records
 * Grain: One row per order and snapshot date
 * Audience: Used for operational reporting and retention analysis
 * Dependency graph: [link]
 */
record OrdersSnapshot { ... }

3. Relational context (20 points)

The question: Does the schema include lineage and upstream provenance?

What we are looking for:

• Table lineage (Source / Used by) (6 pts): where the data comes from and where it goes next.
• Cardinality hints (5 pts): documented 1:1, 1:N, and N:M relationships so agents know whether a JOIN will multiply rows.
• JOIN keys with explicit columns (5 pts): Can an agent determine how to join tables without guessing?
• Data flow narratives (4 pts): refresh cadence, latency expectations, and pipeline dependencies.

Before:

long? individual_field

After:

@InheritDoc("TypesOfIFs.name") <--- Decorator saying we inherit the description from somewhere else 
long? individual_field

4. Constraint validation (15 points)

The question: Can the claims be verified against reality?

Documentation that says “this column is unique” when it is not actually unique in production is worse than no documentation at all: it is actively misleading. This dimension rewards constraints that can be verified.

Critical rule: only constraints that are ACTUALLY DECLARED using formal annotations (@Unique, @ForeignKey, @Check) count. “Implicit” or “obvious” constraints score zero.

What we are looking for:

• Uniqueness constraints (5 pts): @Unique is declared, not merely an id field.
• Business rule validations (4 pts): domain logic such as “if status = 'active', churn_date must be NULL”.
• Verified referential integrity (6 pts): the FK is declared and the referenced table exists in the schema.

This is also where there is plenty of room for interpretation on the agent side. How do we know whether @Unique has been declared for every field that is truly unique? Only by checking the database. And, to be fair, that is something an agent can do in one pass. It may take a little time, but once documented, it is work you do not have to repeat later.

5. Human–AI comprehension (10 points)

The question: Can an agent understand this without domain knowledge?

Descriptions overloaded with jargon, unexplained acronyms, or incomplete documentation around edge cases undermine comprehension for both humans and agents.

What we are looking for:

• Edge-case documentation (3 pts): historical gaps, known quirks, and exceptions explicitly called out.
• Terminology clarity (4 pts): domain terms, acronyms, and internal names defined within the schema (or indicated with unequivocal links).
• Business context (3 pts): why this table exists, who uses it, and what decisions it helps support.

Two tools to make improvement less painful

That looks like a cool rubric, but nobody wants to manually review table by table. So I built two Claude Code skills to make the process more repeatable. I created two skills.

1. Evaluate Schema for AI Readiness

This skill runs the rubric against a schema file and produces a prioritized list of concrete recommendations. You can point it to a repository file or paste the schema directly. In a few minutes, it tells you not just the score but, much more importantly, what to fix first if you want the score to improve, and as a corollary, how tables in a given schema score against the others.

2. /schema-improvement

This one is modular. Instead of trying to improve everything in one giant pass, it works phase by phase:

• Phase 1: adds a protocol-level header with data sources, table types, naming conventions, and reference links
• Phase 2: documents each table with purpose, grain, and intended audience
• Phase 3: documents fields, identifies primary keys, annotates foreign keys, and detects categorical fields that need valid-value enumeration
• Phase 4: removes duplicated documentation by pointing repeated fields back to a canonical source
• Phase 5 (optional): checks production data for fields marked nullable that are never actually null, then tightens the schema accordingly

The design principles behind it are modularity and progressive disclosure: each phase loads only the context (instructions) it needs. That keeps the process leaner, more reliable, and easier to parallelize when schemas are large.

Why this matters beyond AI

It would be easy to frame this as an AI-only problem, but I do not think it is. The schemas that behave better with agents are usually the schemas that were already better for humans. More explicit documentation helps new analysts onboard faster, reduces silent analytical errors, and makes data work less dependent on oral tradition.

The difference is that AI exposes weaknesses in a different way. Sooner, but not always in a visible way. A human analyst can ask follow-up questions. An agent often cannot, and it fills the gaps with feasible assumptions. So the cost of ambiguity becomes visible much faster.

That is also why I like the rubric approach. Tools such as RAG or evaluation frameworks often focus on outputs: did the model produce a good answer? Useful question. But there is another one upstream from it: was the input structured and documented well enough to support a good answer in the first place?

In simpler words: better input does not guarantee perfect output, obviously. But poor input almost guarantees expensive confusion.

Reference and standards

Academic Papers

1. Datasheets for Datasets (Communications of the ACM, 2021). Key contribution: Establishes that datasets are not self-documenting. Questions like “What do the instances represent?”, “What data does each instance consist of?” “Is there information missing?”
2. Model Cards for Model Reporting (2019) Introduces structured documentation for ML models, including performance metrics.
3. FAIR Guiding Principles Wilkinson et al. establish principles to make data Findable, Accessible, Interoperable, and Reusable.
4. Data Cards Playbook: Google Research team created a toolkit for creating structured dataset summaries. Used in production at Google, shows that good documentation requires intentional structure, not ad-hoc comments

Industry Standards

5. Croissant: ML Dataset Metadata Standard. The incipient standard for ML dataset metadata ==> Croissant defines a machine-readable format for dataset discovery and loading. Includes distribution formats, field-level schema with semantic types, record sets, and relationships. More info
6. HuggingFace Dataset Cards — Practical implementation of Datasheets concept. YAML + Markdown format (human AND machine readable). Shows that lightweight, version-controlled documentation works at scale. Standard Doc for datasets hosted on the HuggingFace Hub. See documentation
7. Dataset Nutrition Label — Analogy with food nutrition labels for datasets. 7 modules: Metadata, Provenance, Variables, Statistics, Pair Plots, Inferential, Updates. Project | Article

EVAL Frameworks

8. Ragas Documentation — Framework for evaluating RAG (Retrieval-Augmented Generation) systems. Metrics: Faithfulness (hallucination detection), Context Relevancy, Answer Relevancy. Moves beyond “vibe checks” to measurable quality. Key contribution: Shows that schema quality directly impacts AI response quality. Poor schema docs → Low faithfulness (hallucinations). Missing constraints → Incorrect query generation. Ragas Metrics
9. DeepEval — LLM Evaluation Framework with specific metrics for RAG. See repo
10. LlamaIndex Retrieval Evaluation Retrieval-focused metrics: MRR (Mean Reciprocal Rank), Hit Rate, Precision. Shows that documentation quality affects search result rankings. Application: Richer annotations (like explicit FKs) should improve retrieval ranking by providing more semantic signals for matching.
    • High MRR (→1.0) = finds it fast = fewer tokens spent, less context wasted
    • Low MRR (→0.1) = has to scan many results = higher chance of error or running out of context