Giving an agent a map: grounding LLMs in your data model
Once you've accepted that a semantic layer is the foundation, the next question is mechanical: how do you actually hand your data model to an agent so it can use it? "Put the schema in the prompt" works for a toy and falls over the moment you have 400 tables. Here's the pattern I reach for.
Don't dump the schema — index it
Stuffing every table and column into context is expensive, noisy, and blows past the window. Instead, treat your model like a knowledge base the agent retrieves against:
- Write a short, plain-language description for every entity and metric.
- Embed those descriptions and store them in a vector index.
- At question time, retrieve only the handful of entities, metrics, and join paths relevant to the question, and put those in context.
The agent sees a focused, relevant map — not the whole city. Retrieval quality here matters more than model size.
Give it tools, not a SQL console
A grounded agent shouldn't be writing raw SQL against production. It should call typed tools that encode the safe, sanctioned operations:
get_metric(name, dimensions, filters, grain)— resolves to your semantic layer's definition, not hand-written SQL.list_entities()/describe_entity(name)— navigation.run_validated_query(spec)— a structured query object your layer compiles, so the agent can't express something invalid.
Tools turn "generate arbitrary SQL and hope" into "compose known-good building blocks." The model's job shrinks to planning — which is exactly what it's good at.
Make definitions first-class context
Every metric and dimension the agent can touch should carry its description, its units, its grain, and its gotchas ("excludes refunds," "billing account, not user"). This is the context a human analyst carries in their head. Written down, it's the difference between an agent that asks "did you mean billing account or user?" and one that silently picks wrong.
Close the loop with feedback
Log every question, the entities retrieved, the query run, and whether the answer was accepted. That log is gold: it shows you which descriptions are ambiguous, which metrics are missing, and where the model keeps reaching for something that doesn't exist yet. Your semantic layer should improve every time the agent stumbles.
The payoff
Do this and the agent stops feeling like a party trick and starts feeling like a junior analyst who actually read the data dictionary — fast, grounded, and honest about the edges of what it knows. The magic isn't in the model. It's in the map you gave it.
Next: stitching these pieces into an end-to-end agentic pipeline, from question to action.