Introducing decisions & rationale capture on the API & in App

Facts can now carry a rationale, the reason a version was created with its sources, written by agents and the assistant and shown wherever you review facts.

Until now a fact told you what it said but not why it was recorded. When a version landed in your approval queue, you had the claim in front of you but no record of the note, page or insight it came from, or the reasoning behind it.

What's new

• A rationale on every new fact version. create_fact over MCP and REST, and the assistant's updateFact, now accept an optional rationale: the reason a fact version was created, together with its sources. It needs at least one real source, a note, a page, an insight or a quote from the conversation.
• Shown where you review. The rationale appears on the approval card, in a block's version history, and in the decision details panel, hidden when there is none.
• Readable over the API. MCP list_facts and GET /facts/{factId}/versions return each version's rationale, or null.
• No change requests as reasons. The guidance to writers now says a request to change a fact is not a rationale, so an agent records why the fact is true rather than quoting the instruction it was given.

Why it matters

When you sit down to approve a batch of facts an agent proposed overnight, the rationale is the difference between trusting a claim and chasing down where it came from. You see the note or page behind each one before you decide it becomes truth. Nothing becomes verified without a person, and now that person has the reasoning in hand.

Where to find it

Open the approval queue or any block's version history on the Facts page, or read the decision details panel. Over the API, pass rationale on create_fact and read it back on list_facts and fact versions, documented at api.getnoan.com.

Good to know: for the assistant, the conversation's chat thread is recorded as a source but kept private, so it is left out of what the API returns.