Give the model the schema it queries, in context: descriptions, keys, codes, sample values

When the model writes SQL or structured filters, put the schema it is querying in its context: table and column descriptions, key relationships, what enum codes and nulls mean, sample values. Give it directly, in the prompt or as files it reads, rather than behind a search tool. This holds while the schema fits in a modest share of the window; past that, link it by exploration (8.b.ii). Making the schema context good (names, descriptions, examples) is data-side work.

Tier 3 because it changes what the model sees.

When it applies

• In the code: a SQL-writing agent with no table and column descriptions, keys or allowed values in its context; schema context reachable only through a search tool
• In traces: queries against non-existent columns, wrong joins, guessed enum codes; failure rows labeled tool-hallucination (names) or domain-knowledge-deficit
• In eval results: failures from wrong table, column or value

How

1. Count the schema's tokens with descriptions and sample values; if it takes more than a modest share of the window, use 8.b.ii instead.
2. Write or generate the missing descriptions: column meanings, keys, enum codes, null semantics.
3. Put the schema in the prompt, or mount it as files, instead of a retrieval tool.
4. Paired eval on execution accuracy and wrong-table, wrong-column and wrong-value failures.

How to measure it

• experiment (tier 3): paired eval with and without the schema context, on execution accuracy

To compare the change against your agent's current version, with the same cases and enough repeats to see past run-to-run noise, use aot-evals.

Expected impact

• Quality: improves, large: Cube: +17 to +23 points from a semantic-context document on 99 questions (Apr 2026)
• Cost: degrades, small: the schema costs prompt tokens on every call; caching the prefix (3.b.i) recovers most of it
• Performance: none

Caveats

The measured gain comes from a semantic-layer vendor's study (Cube) on one 25-table schema. Past a modest share of the window, loading the whole schema costs more than it returns; that is 8.b.ii.

Evidence

Evidence comes from: Data analysis.

1. Mount raw semantic-layer files instead of retrieval tools

   Same bundled 5-query result. "The semantic layer is already great documentation ... We were building tools to summarize what was already legible. Claude just needed access to read it directly." Code: sandbox.writeFiles(files) from ./semantic-catalog.

   Andrew Qu (Vercel), "We removed 80% of our agent's tools" · Dec 2025 · v2: The file system is the agent

2. Add a hand-authored semantic-layer document to the prompt

   n=99, single shot, analytical verdict. Opus 4.7 50.5% -> 67.7% (+17.2 pp, McNemar b/c 22/5, p=0.0015); Sonnet 4.6 46.5% -> 68.7% (+22.2 pp, 30/8, p=0.0005); GPT-5.4 45.5% -> 68.7% (+23.2 pp, 27/4, p<0.0001). The document also broke 4-8 previously passing questions per model (the c counts). Mean input tokens rose ~2-4K per query (e.g. Sonnet 14,364 -> 17,303); latency changed -0.9 to +1.8 s. Document written once and not iterated against the benchmark; residual ~30% failures sit on percentiles, correlation, stddev, ABC classification, threshold ranking and complex CTE shapes.

   Michael Rumiantsau, Ivan Fokeev (Cube), "Semantic Layers for Reliable LLM-Powered Data Analytics: A Paired Benchmark of Accuracy and Hallucination Across Three Frontier Models" · Apr 2026 · Section 4.2 Conditions; Table 1; Section 5.4; REPORT.md 2.2

3. Put the semantic context in the prompt, not behind searchNot measured

   Reported only in passing (Section 6.5; REPORT.md 3.5): "did not significantly outperform raw-DDL Claude on this benchmark"; numbers not given in the paper. 25-table schema, so everything fit in context; the authors flag 1,000+ table warehouses as open.

   Michael Rumiantsau, Ivan Fokeev (Cube), "Semantic Layers for Reliable LLM-Powered Data Analytics: A Paired Benchmark of Accuracy and Hallucination Across Three Frontier Models" · Apr 2026 · Section 6.5 Limitations; REPORT.md 3.5

4. Render tables as CREATE TABLE with extended column descriptionsNot measured

   Described in §2.2.2; not ablated separately.

   Albert Chen, Manas Bundele, Gaurav Ahlawat, et al. (LinkedIn), "Text-to-SQL for Enterprise Data Analytics" · Jul 2025Older evidence · §2.2.2

Related

• 8.b.iiLink large schemas by exploration: start broad, grow the linked set with probing queries, favor recall
• 8.a.iiSurface information the source holds but the agent cannot read
• 7.a.iRoute metric questions through a deterministic semantic layer; fall back to text-to-SQL
• 3.b.iKeep the prompt prefix cache-stable
• 9.a.iFeed back a sound external verifier's verdict; never the model's own critique
• 8.a.iChoose the retriever by corpus size and question type
• 3.a.iAdd worked examples to the prompt (few-shot), or curated example queries for data agents
• 8.b.iTune the search tool: snippets, enough results, retries, reformulation, filters, source quality

In Claude Code

This optimization is a skill in aot-kit, our open-source Claude Code plugin: /aot-kit:ground-queries-in-schema. Its library entry holds every source. Have new evidence, or a correction? Suggest a change.