KeyChat

Ask questions about your data in plain language and read grounded, cited answers. About 6 minutes.

KeyChat is KeyOne’s conversational analyst. Instead of building a report, you just ask — “What are the top risks this week?” — and get an answer back in plain English, with its sources attached. It’s the fastest way to triage what’s happening across your stores and then jump straight into the work.

KeyChat has two surfaces over one thread store:

The rail — the chat toggle in the topbar slides KeyChat in as a persistent right-hand rail alongside whatever page you are on (⌘K “Ask KeyChat” opens the same rail). Best for quick asks while you work.
There is no separate page — the rail IS the analyst surface. Visiting /app/chat simply opens the rail over whatever you were looking at.

Both read and write the same saved threads, so you can start in the rail and continue on the full page.

What you’re looking at

When KeyChat opens you’ll see:

A header with the thread title, a History button (the thread library) and a New thread button. On the full page the header also carries the thread’s entity anchor.
The conversation area, where the back-and-forth appears — your messages on the right, KeyChat’s replies on the left.
An input box pinned to the bottom for typing your question.

Before you’ve asked anything, the conversation area shows an empty state with a few suggested prompts you can tap to get going.

Threads & investigations

Every conversation is a saved thread: it’s persisted the moment you send your first question, auto-titled from that question, and listed newest-first under History with its title, entity chip, and last-updated time. Select a thread to reload it; New thread starts fresh; hover a row to rename or delete it.

A thread becomes an investigation — the concept that used to live on the separate Explore page — when you:

Name it — rename inline (click the title on the full page, or the pencil in the History list), and
Anchor it — click the anchor dot / crosshair next to the thread title in the rail header and pick a type (store, product/SKU, category, region, rep) plus the entity’s name and optional id.

Same object, no separate surface: the anchor shows as a colored chip on the thread, and it’s passed to the analyst as context so answers stay focused on that entity. Clearing the anchor demotes the investigation back to a plain thread.

Honest note: if the database is unavailable, the thread list shows an honest empty state and your conversation still works — it just isn’t persisted for later.

Asking a question

Type your question in the input box and press Enter to send. Need a second line? Press Shift+Enter for a newline without sending.

Ask the way you’d ask a colleague — full sentences are fine, and you can follow up to refine. KeyChat keeps the thread, so “and which of those is worst?” works as a follow-up to your last question.

The suggested prompts on the empty state are a good starting point:

“What are the top risks this week?”
“What decisions are open for store KS_00001?”
“Why did rate of sale drop at GreenMart?”

(GreenMart is an illustrative store label, used here as an example — substitute your own store, region, or SKU.)

Reading an answer

Answers appear in the conversation, your questions right-aligned and KeyChat’s replies left-aligned. A reply can include:

The answer itself, with light formatting — bold text, bullet lists, and dividers to keep things readable.
Citation chips — small tags showing exactly which tool, which record ID, and a label the figure came from. Each number traces back to a specific source.
Tool badges — showing which underlying tools KeyChat called to assemble the answer.

Those citations are the point: every figure KeyChat gives you is traceable. You’re never asked to take a number on faith — you can see where it came from, down to the record.

Tip: Skim the citation chips before you act on a surprising number. If a figure has a chip, it’s pulled from your data; if a claim has no chip, treat it as framing or interpretation, not a measured fact.

Grounded and honest by design

The scope banner in the header spells out how KeyChat works:

Your questions run under your own token scope — read access plus author:metric. KeyChat can only see and answer within what you’re permitted to see.
Raw-SQL access is reserved for analyst accounts. If you need to run arbitrary SQL, that’s an analyst capability, not something KeyChat does on a standard token.
Answers are grounded and cited, not fabricated. KeyChat answers from your data; it doesn’t invent figures to fill a gap.

If KeyChat can’t ground an answer, it tells you — rather than guessing.

What KeyChat can and cannot do

KeyChat answers questions about your own data. It does not change anything. Every tool it can call is read-only, and there is no path by which a conversation creates, assigns, or modifies a record.

That is a deliberate boundary, not a gap waiting to be filled: an assistant that can be talked into filing work is an assistant whose output nobody can trust as a record of what actually happened. Creating a task, assigning it, launching a campaign or changing a decision are all done in the product, by a person, where the action is attributable.

The tools it calls are these, and no others:

Tool	What it does
`list_hubs`	List the analytics hubs configured for this tenant
`list_queries`	List the saved, read-only queries this tenant’s own users have written
`list_query_definitions`	List the analytics queries KeyOne ships — the authored library behind the hubs — with the first paragraph of each one’s description
`describe_query`	Read one query in full before running it: the whole description, and every parameter with its type, its default and any declared set of legal values
`run_saved_query`	Run a query from either catalogue, by id
`list_decision_definitions`	List the detection rules configured for this tenant
`list_decisions`	List currently-open decisions
`list_dimension_values`	List the real values of one dimension — region, channel, category — before filtering by one
`describe_vocabulary`	Report which canonical fields this tenant has actually bound
`present`	Render the answer’s charts, tables, ranked lists and KPI cards — a display step, it reads nothing and writes nothing
`run_adhoc_sql`	Run read-only SQL written in canonical fields — off unless a deployment explicitly enables it

Every one of them that touches your data runs through the same read-only query path a person uses, with the same row caps. KeyChat gets no privileged access to your data. (present is the exception that touches none of it: it is how KeyChat draws a chart or a table of figures it has already fetched, and the blocks it sends are checked against what this product can actually render before any of them reaches you.)

Tool calls are always visible in the conversation — you see which tool was called and what it was asked before the answer arrives.

When no analyst provider is configured

KeyChat’s written answers come from a language model your deployment configures — an analyst provider with an API key, set by an administrator. If none is configured, KeyChat says so plainly:

“Written answers are off — no analyst provider is configured. Drill-downs opened from a chart or table still work.”

Drill-downs are the part that never needed a model: clicking an outlet, product or rep anywhere in KeyOne opens its breakdown in the rail, read straight from your data, with the query behind each figure one tab away. Everything already in your threads stays readable too. What you lose without a provider is the typed question and its written answer — and KeyChat does not fabricate one to fill the gap.

If you’re seeing that notice, the fix is on the setup side: an administrator configures the provider in the deployment’s configuration. Check the FAQ or ask your administrator.

Writing good questions

KeyChat rewards specificity. The more precise your question, the tighter the answer:

Name the thing. Reference a specific store, region, SKU, or timeframe — “for store KS_00001”, “this week”, “in the North region” — instead of asking in the abstract.
Follow up to drill down. Start broad, then narrow: ask for the top risks, then ask “why?” on the one that matters, then ask “what should I do about it?”
Use it to triage, then act. KeyChat is good for figuring out where to focus. Once you know, open Decisions or the hub itself to work the cards.

Some realistic, illustrative questions an FMCG user might ask:

“Which stores in the East region have the most open risks right now?”
“What’s the rate of sale trend for SKU 88421 over the last 8 weeks?”
“What is open for store KS_00042, ranked by value impact?”
“Why is availability down at FreshFields this week?”
“Which three actions would lift sales the most across my territory?”
“Compare on-shelf availability between store KS_00001 and KS_00007.”

(FreshFields and the store/SKU codes above are illustrative — use your own.)

A worked example

Data below is illustrative.

You ask:

“Why did rate of sale drop at GreenMart this week?”

KeyChat replies (left-aligned):

Rate of sale at GreenMart (KS_00013) fell ~18% week-over-week, driven mainly by:

Out-of-stock on SKU 88421 for 3 of the last 7 days [availability · rec_4471 · OOS days]

A price increase of 6% that took effect Monday [pricing · rec_5582 · list price]

The availability gap looks like the larger factor. Tools called: availability, pricing, rate_of_sale.

Notice the citation chips ([tool · record ID · label]) on each figure and the tool badges at the end. You can trust each number because you can see its source.

You follow up:

“What should I do about the out-of-stock?”

KeyChat will point you to the relevant decision — and that’s your cue to open it in Decisions.

Common pitfalls

Asking for data outside your scope. KeyChat answers within your access scope. If you ask about a store or region you’re not permitted to see, it can’t return those figures — that’s the permission model working, not a bug.
Expecting raw SQL. Arbitrary SQL queries need an analyst account. KeyChat on a standard token answers through its grounded tools, not free-form SQL.
Expecting it to fabricate. If KeyChat can’t ground an answer in your data, it says so instead of making something up. A “no” or “I can’t ground that” is the honest answer, not a failure.
Expecting written answers with no provider. If the rail says written answers are off, no analyst provider is configured for your deployment — drill-downs still work, typed questions do not, until an administrator configures one.

Tip: If an answer seems thin, check for that notice first, then try making the question more specific. Both are common, easy fixes.

Using a Hub — where to act on what KeyChat surfaces
Notifications — your queue of decisions to work
Understanding a Decision’s Value — what the number on a decision measures, and in which unit
FAQ — provisioning, scope, and common questions
Glossary — terms like rate of sale, days of cover, and on-shelf availability

Next: KeyLink for Field Reps