Methodology
Anthropic and OpenAI both published how they make data agents accurate inside their own walls, and both landed on the same bottleneck: context, not SQL generation. ClariLayer is the context layer that checks itself, delivered over MCP for one analyst or RevOps operator — no data team required.
Both posts describe the same architecture from different angles: accuracy comes from giving the agent structured, checked, maintained context — not from a better SQL generator and not from dumping more documents into retrieval. Both also describe an internal machine: canonical datasets, curated annotations, eval suites, and engineers to keep it all fresh.
ClariLayer starts from the analyst those posts do not serve: one person in claude.ai, Claude Code, Cursor, or Codex, working against their own — often messy, ungoverned — warehouse or CRM context, with no platform team to build the machine for them. This page lays out the principles we build by, so you can judge the approach before you connect anything.
An agent can have the right context served and still not use it. Anthropic reported a sharp ablation: giving the agent raw retrieval access to thousands of prior queries moved accuracy by less than a point. The information was available, but unstructured retrieval still could not map a new question to the right precedent. The bottleneck was structure, not access.
Our own agent tests reproduced the same failure at individual-analyst scale: the right definition retrieved, then a filter invented that was never in it, an aggregate computed at the wrong grain, a stale note preferred over a checked contract. Serving context is table stakes. The work — and everything below — is about making the checked contract the thing the agent actually uses.
We also ran the counterfactual. In our internal paired eval — three batteries, 38 pre-registered data questions, the same agent with and without the layer — the agent scored 36/38 with ClariLayer connected against 26/38 without. The cheaper the model, the bigger the lift: the control went confidently wrong under session load.
Six principles
Each one is a response to a failure we have actually watched an agent make. Together they are the difference between a notes file your agent might read and a context layer it can be held to. For the mechanics underneath these principles, see how the context layer works.
ClariLayer gives the connected agent standing instructions to recall saved context before writing SQL. The agent has an in-flow MCP tool it can call without you pasting a prompt each session; you maintain durable context, not a magic prompt.
A definition here is data, not a paragraph: warehouse contracts carry source table, grain, filters, and expected columns; CRM contracts carry provider, object, property, expected values, aliases, and labels. Structure makes a contract checkable and routable.
Each explicit reconcile checks one compatible saved definition. Warehouse contracts use agent-supplied actual_sample; HubSpot contracts use bounded, recursively row-free crm_evidence. A declared-vs-actual mismatch surfaces as a caveat. Otherwise the entry stays asserted.
When the best match comes from a different use case, it is labeled as such rather than passed off as a clean hit. When a question is ambiguous, the candidate scopes are named instead of one being guessed. Caveats ride with the contract, so the agent knows what to treat with care.
When a standing rule conflicts with a checked contract, the agent surfaces the conflict and proposes an update for your review. It never silently rewrites canon — and never silently drops your rule. You stay the editor of record for your own context.
When the agent reaches for the wrong context, we use that failure to harden the routing behavior before it ships again.
Where it sits
Your live source
Warehouse or HubSpot, under your agent’s own authorization. ClariLayer never connects.
Your agent
claude.ai, Claude Code, Cursor, or Codex connected to ClariLayer over MCP.
ClariLayer context layer
Returns context with provenance, status, and caveats. Compares one compatible contract per reconcile.
Recall, routing, and labels travel over MCP. Reconcile is agent-mediated: warehouse contracts accept actual_sample columns, an optional row count, and optional preview rows; HubSpot contracts accept bounded property metadata and aggregate distributions in crm_evidence, with CRM rows forbidden. HubSpot reconcile is generally available. In this personal MCP path, ClariLayer never holds source credentials, executes SQL, or calls HubSpot. The full data-flow, including what we will not pretend about preview rows, is on the security page.
Bounded completion receipt
Managed instructions establish a concrete completion loop for relevant data work: recall first, make any confirmed live write or reconcile update, then call context_checkpoint. If nothing durable changed, no_update_required is allowed only after the relevant metric, mapping, filter, grain, and source-of-truth facets were reviewed. A pending proposal alone cannot complete the loop, and update_failed explicitly blocks completion.
A successful checkpoint durably and idempotently persists the agent's constrained context_updated or no_update_required declaration and validates ownership and eligibility of referenced ClariLayer objects. It does not independently prove an entry changed or external work happened, and it does not certify code, deployment, Databricks validation, query output, HubSpot state, or semantic correctness in any external system.
Plenty of tools will happily stamp your definition “verified.” We won’t — a false all-clear is the one failure a trust product can’t survive. Today reconcile emits caveat on a declared-vs-actual mismatch and asserted otherwise. The stronger verified status is not live and remains gated off, with no public release timeline. Every mark you see today is one we can back.
Honest comparisons against the two things analysts reach for first: a hand-written CLAUDE.md and a semantic layer or catalog.
Read the comparisonsWhat touches your data and where it goes — no source credentials, no server-side SQL, no HubSpot calls, and two explicit evidence boundaries.
Read the security pageConnect ClariLayer to claude.ai, Claude Code, Cursor, or Codex. Bootstrap SQL, dbt, CLAUDE.md, a dictionary, or a semantic model; reconcile the definitions that matter; then let your agent recall the checked contract in-flow.
We use privacy-friendly analytics
With your consent we use PostHog and Vercel Analytics to understand how ClariLayer is used so we can improve it. We never sell your data. Errors are always monitored (without analytics) so we can keep the app reliable. You can change your mind anytime.