Agent-ready modeling

The schema is the largest single thing an agent reads before it writes a query. Every unclear name spends tokens and buys a guess, so naming stops being a style preference and becomes an accuracy lever:

• net_revenue, not amt2. A name that needs a glossary needs the glossary in the context window.
• is_declined, not flag3. A boolean named after its meaning can be summed into a numerator. A boolean named after its position cannot.
• Grain in the view name. v_sales_line says one row is one line. v_sales would not.
• Different facts, different names. list_price on the product and unit_price on the line - the naming is what stops an agent treating them as the same number (session b2's point, now load-bearing).

You can tell an agent "never join the two fact tables". It will mostly comply. Or you can build the access layer so that no view exposes both facts, and the join becomes unwritable - which is what sql/40_agent_views.sql does.

Prefer the second every time. The general principle: constraints beat instructions. An instruction is probabilistic and competes with everything else in the context window; a schema that lacks the dangerous path is deterministic. Applied to Bazaar:

• Read-only credentials on views only. No base tables, no writes. python/agent_text_to_sql.py also enforces this in code, twice - an allowlist regex and a read-only SQLite connection.
• No fact-to-fact path. The two facts are never both reachable in one view, so the double-count query cannot be expressed.
• Pre-split measures. approved_amount and declined_amount exist so that no ratio has to be stored, so no average of averages is available to compute.
• Unknown members instead of NULLs. A NULL dimension key silently drops rows from an inner join; a -1 unknown row keeps them countable (session b6).

The highest-leverage single object in the whole model is a table of metric definitions inside the database. Six columns: name, definition, SQL expression, source view, grain, caveat. Thirteen rows for Bazaar.

SELECT metric_name, sql_expression, grain, caveat
FROM v_metric_definitions
WHERE metric_name IN ('net_revenue', 'orders', 'aov', 'decline_rate');

Note the caveat column - it is the one people leave out and the one that saves the most damage. "Never average an AOV." "Below ~30 attempts it is noise." "Carts, not sessions." Those sentences are the difference between a metric an agent can use and a metric an agent can misuse fluently.

The return trip matters as much. A fluent sentence around a wrong number is worse than a table, because it removes the reader's last chance to notice. python/agent_query_to_text.py narrates deterministically from the model's own metadata: it classifies each column from its name, demands a denominator for anything that looks like a rate, flags small samples against the 30-observation floor, and appends the contract's caveat for any metric the result names.

SELECT payment_method_label,
       COUNT(*)          AS attempts,
       SUM(is_declined)  AS declines,
       ROUND(100.0 * SUM(is_declined) / COUNT(*), 2) AS decline_rate_pct
FROM v_payment_attempt
GROUP BY payment_method_label
HAVING COUNT(*) >= 30
ORDER BY decline_rate_pct DESC;

Drop the HAVING clause and re-run. A method with a handful of attempts jumps to the top of the ranking. The model cannot stop someone asking for that; the caveat and the visible denominator are what stop them acting on it.

All three live in python/ and all three run offline, with no API key, so nothing here is a demo you cannot reproduce.

• agent_text_to_sql.py - the full loop against the live Claude API: schema card as system prompt, one strict run_sql tool, a read-only allowlist guard, results fed back until it answers. --offline uses the recorded golden queries instead; --no-contract withholds the schema card so you can watch it fail.
• agent_query_to_text.py - narration. --golden q14 narrates a golden question; --llm adds a Claude-written version grounded on the deterministic facts, so the prose cannot contradict the metadata.
• eval_golden_questions.py - the scorecard. --mode grounded scores 20/20, --mode naive scores 0/20, --mode live calls a real model with or without the contract.