ADR-0023: What a model reads is a catalog — one general read tool, an index always present, entries described on demand, rules computed by the domain

  • Status: Accepted
  • Date: 2026-11-06
  • Scope: core (any backend feature where a language model answers questions over a user’s or a
    tenant’s data)

Context

The first way to give a model data is one tool per screen: a snapshot tool, a budget tool, a
category tool. Expenses built that, and it went wrong in ways any project would repeat (expenses
0009-ai-analysis-sandbox):

  • every new question needed a new tool, and the model was steered to the wrong one by a routing
    table in the prompt;
  • a tool returned a fixed shape, so anything else had to be computed by the model in its head,
    where its arithmetic was wrong;
  • a business rule (what counts as spending, which invoice a purchase belongs to) was restated in
    each tool’s description, and the copies drifted from the code;
  • describing every table and column in every request cost tokens on every turn, and the
    description itself became something the model could recite.

Decision

1. One general read tool over a sandboxed query engine

The model reads through one tool that runs a read-only query over a per-request engine holding
only the caller’s rows. The model composes the query; the engine computes every number. The
sandbox’s protections (data only, one statement, statement kind, engine catalog denied, limits,
timeout) are code, per 0019-llm-features-prompts-shape-code-enforces.

2. A business rule enters as a column the domain computed

When a figure depends on a rule, the sandbox carries it as a column filled by the same domain
method
the screen’s endpoint uses. The model never re-derives a rule in SQL. If the rule
changes, the screen and the model move together.

3. Views are the screen’s own use case, held equal by a test

Where a figure is what a screen shows, the catalog offers a view whose rows come from the use
case that screen calls, mounted only when a query reads it. A parity test holds the view equal to
the endpoint, and an isolation test holds every row to the caller.

4. Two levels: an index always present, entries described on demand

The tool’s description carries a short index of entries (id and one-line purpose). The model asks
for an entry’s columns, guide and rules when it needs them. The index is built once at startup
from code, is identical for every user, and so sits in the shared cached prefix
(0025-prompt-cache-spend-every-breakpoint-most-stable-first).

5. Rules travel with their entry; a detector turns a known mistake into advice

An entry’s rules (cash flow is not spending; never sum a parent cap and its child) live on the
entry, not in the system prompt. Where a rule can be recognised in a query, a detector attaches
its text to the result as a warning. A warning is advice: the query still runs. An empty result
lists the values that do exist, so the model can see its filter was wrong.

6. The catalog is internal

The model writes queries with it and never names it back to the user. That instruction sits
inline next to the catalog, where it holds, and code denies the engine’s own catalog.

Consequences

  • A new question usually needs no new tool. A new entry is a class with a card, and it ships with
    its parity and isolation tests.
  • The model’s arithmetic moves into the engine, and a figure in an answer can be traced to a query.
  • Accepted: a turn takes more model calls (describe, then query) than a fixed tool did. The
    index keeps the first call cheap, and the cache keeps the rest cheap.
  • Tables that are not the user’s subject (sessions, logs, billing with us) are never mounted:
    whatever the sandbox holds is what an injection could leak.