Your SQL agent is lying to you, and it doesn't even know it. The agent connects to your database, sees a column named status, finds the value 'active', and confidently returns a count. But in your actual business logic, 'active customer' means someone who placed a paid order in the last 90 days. The database doesn't know that rule. The wiki does. The data team knows. The agent guesses, the query runs without errors, and you get a wrong number that looks right. This is the silent failure mode of current AI agents: they can read schemas but not business context.

The 48% Ceiling on LiveSQLBench

This isn't just a theoretical edge case. LiveSQLBench, a public benchmark for AI-to-SQL translation, puts agents in exactly this trap. It tests 18 databases across topics like disaster response and crypto trading. Each database comes with three distinct files: the schema, column descriptions, and a separate file of business rules. Most questions rely on terms defined only in that third file. When an agent tries to find 'high-risk operations' in a disaster database, it might see a safetyranking column and stop there. But the actual rule requires three conditions across two tables: emerglevel is Red or Black, safetyranking is High Risk, AND secincidentcount is over 50. The best system on the leaderboard currently answers only 48% of these tasks correctly. We are nowhere near production-ready accuracy if we rely on schema alone.

Building the OKF Bundle

Lakhan Malviya's new series on DEV.to proposes a third option beyond pasting everything into the prompt (which explodes token costs) or letting the agent guess (which fails accuracy). The solution is an OKF bundle: a folder of small markdown 'concept files' that separate schema, definitions, and rules. In Part 2, the author walks through manually creating these files for the disaster database. You start with a table concept file that merges the raw schema and column descriptions into a single markdown document with YAML frontmatter. Then, you create separate knowledge files for business rules, such as the Resource Utilization Ratio (RUR). The key innovation here is linking. The RUR formula file links to the columns it uses, and the Classification file links back to the RUR formula. This creates a navigable graph of business logic that an agent can traverse step-by-step.

Progressive Disclosure for Agents

The agent doesn't read the whole bundle at once. It uses 'progressive disclosure.' First, it reads a root index.md file that acts as a menu. This index points to folder-level indexes for tables/ and knowledge/. When the agent needs to answer a question about 'Resource Utilization,' it opens the knowledge index, finds the RUR file, reads the formula, and sees a link to the distributionhubs table. It opens that table file only if it needs the column types. This mimics how a human analyst would navigate a well-organized wiki. The bundle structure is explicit: tables/ for schema and knowledge/ for rules, with optional frontmatter declaring the OKF version. By isolating business logic into linked, lightweight markdown files, you prevent the agent from drowning in irrelevant context while ensuring it never misses a critical definition.

Key Takeaways

  • SQL agents fail primarily due to missing business context, not schema misunderstanding, with top benchmarks hitting only 48% accuracy.
  • OKF bundles separate schema, column meanings, and business rules into linked markdown files to enable precise agent navigation.
  • Progressive disclosure allows agents to read only relevant index and concept files, reducing token costs while maintaining accuracy.
  • Business rules must be explicitly linked to schema columns; raw rule files often lack table references, causing agent confusion.
  • The LiveSQLBench Base-Lite dataset (18 databases, 270 questions) serves as the primary testbed for this knowledge-layer approach.

The Bottom Line

Stop expecting LLMs to hallucinate your business logic. If you want agents that actually work, you have to feed them a structured knowledge layer, not just a raw database dump.