AI agents don't fail at SQL—they fail at knowing which data to trust

The failure mode is predictable. You connect an AI agent to a database, it writes syntactically correct SQL, the query runs, and the answer is wrong. Not wrong because the model is bad—wrong because the agent picked the wrong table, missed a required partition filter, or didn't know that a particular join key is only valid for data after a certain date. The model had no way to know any of that.

LinkedIn ran into exactly this problem at scale and wrote up how they fixed it. Their data context layer is a shared knowledge store that combines AI-generated dataset profiles—built from schemas, query logs, and source code—with human-curated guidance maintained in Git and reviewed through pull requests. When they connected it to their analytics agent, the acceptable-answer rate rose from 25.9% to 79.5%, and median time to answer fell from 10.7 to 4.7 minutes.

Those numbers are striking, but the more useful thing to take from this is the design principle behind them.

The real problem is implicit institutional knowledge

Every data environment accumulates knowledge that lives nowhere except in people's heads and chat threads. Which dataset is the authoritative one when three have similar names. Which metric is fine for engagement reporting but wrong for financial close. Which filters the senior analyst always applies without thinking about it. None of that appears in a schema.

LinkedIn's answer is to make that knowledge explicit and machine-readable, at three levels: global definitions that apply company-wide, team-level playbooks and known issues, and certified analyses that capture the methodology and assumptions behind a specific answer. Critically, AI-generated context and human-curated context are stored separately so the pipeline can refresh its baseline without overwriting corrections that teams have contributed.

That separation matters. Automated enrichment from query logs and source code gives you coverage at scale; human review gives you accuracy where it counts. Neither alone is sufficient.

The Git-as-authoring-workflow choice is deliberate

Routing human-curated context through pull requests isn't just a tooling preference—it enforces review, attribution, and a clear audit trail. Asset owners approve changes the same way they'd approve code changes. Automated checks catch missing or duplicate content before review. After merge, the context is synchronized automatically into the layer where agents can retrieve it.

For small teams, this pattern is worth copying even at modest scale. The discipline of writing knowledge down, having someone else review it, and keeping it in version control is valuable independent of AI agents. When you eventually connect an agent, you already have something to give it.

Progressive disclosure keeps context windows manageable

One detail in the LinkedIn post that deserves more attention is the index tree. Rather than loading all curated context into an agent's context window, the system organizes indexes hierarchically. An agent reads top-level summaries, follows relevant branches, and fetches only the documents it needs. In one example, four index reads are enough to reach the relevant content without loading unrelated material.

This is the right approach to scaling retrieval-augmented systems. A flat dump of everything you know is not context—it's noise. Structure that lets the agent navigate to what matters is what actually moves answer quality.

What this means if you're building something smaller

You don't need LinkedIn's scale to face this problem. Any product that lets an AI agent query a non-trivial data model will run into the same gap between what's in the schema and what a competent analyst actually knows. The fix isn't a better model. It's building the knowledge layer first—even if it starts as a few Markdown files reviewed by the person who knows the data best—and treating that layer as a first-class part of your system, not an afterthought to be stuffed into a system prompt.

Sources

• Inside LinkedIn's data context layer: curating trustworthy context for humans and agents (original)
• Found via the TLDR newsletter