Getting Started
Everything you need to understand Tell and start building with it. From core concepts to your first model.
Understand the Core Idea
Most organisations encode their strategy in slide decks — unstructured documents that can't be queried, versioned, or read by machines. When an AI agent processes thousands of transactions, it has no way to know which ones matter to the strategic bets the company is making.
Tell solves this by giving strategy a format. A Tell model encodes what an organisation is betting on, what assumptions underpin those bets, and what evidence says about whether those assumptions are holding.
GAAP standardised how companies report finances. OpenAPI standardised how services describe their interfaces. Tell standardises how organisations encode strategic intent.
Learn the Key Entities
Tell has seven core entities. The three most important ones to understand first:
Bets — What you're investing in
A bet is a falsifiable hypothesis your organisation is testing with real resources. Not a plan, not a goal — a bet. It has a thesis ("if we do X, then Y will happen"), a confidence level, and a lifecycle status.
Assumptions — What must be true
Every bet rests on assumptions — conditions that must hold for the thesis to work. The critical insight: assumptions can be shared across bets. When a shared assumption breaks, multiple bets are affected simultaneously.
Evidence — What the data says
Evidence is a discrete signal — from a human, an AI agent, or an integration — that supports, weakens, or has neutral bearing on an assumption. Evidence is append-only and immutable.
The remaining entities — Connections, Scenarios, Contributors, and Portfolio — are covered in the full specification.
Write Your First Tell Model
A Tell model is a JSON file with the .tell.json extension. Here's the simplest valid model — a portfolio with one bet and one assumption:
{
"tell_version": "0.2",
"portfolio": {
"id": "portfolio_acme",
"name": "Acme Corp — Strategic Portfolio",
"organisation": "Acme Corp",
"version": 1,
"bets": [
{
"id": "bet_expansion",
"title": "European Market Expansion",
"thesis": "Entering the EU market via Germany
will generate €2M ARR within 12 months",
"status": "active",
"confidence": 65,
"time_horizon": "12 months",
"owner": "ceo",
"assumptions": [
{
"id": "asm_regulatory",
"text": "EU regulatory approval for our
product category by Q2",
"status": "unknown",
"bet_ids": ["bet_expansion"],
"evidence": []
},
{
"id": "asm_demand",
"text": "Sufficient demand in the DACH
region for our pricing tier",
"status": "holding",
"bet_ids": ["bet_expansion"],
"evidence": [
{
"id": "ev_001",
"assumption_id": "asm_demand",
"signal": "supports",
"content": "Market research shows 340
qualified prospects in DACH",
"confidence": "medium",
"source": "human",
"timestamp": "2026-03-01T09:00:00Z"
}
]
}
]
}
],
"connections": [],
"scenarios": [],
"contributors": [
{
"id": "ceo",
"name": "Jane Smith",
"type": "human",
"role": "owner"
}
]
}
}That's it. This model is a valid Tell document that any Tell-compatible system can parse, display, and reason about.
Add Evidence Over Time
The power of Tell becomes clear over time. As evidence accumulates, the model becomes a living record of what your organisation is learning about its bets.
How evidence flows:
- 1.A human contributor or AI agent observes something relevant.
- 2.They append an evidence record with a signal (supports/weakens/neutral), confidence level, and description.
- 3.The assumption's status may change based on accumulated evidence.
- 4.The bet's confidence updates automatically based on its assumptions' evidence.
- 5.If the assumption is shared across bets, all linked bets are affected.
This is what makes Tell different from a spreadsheet or a slide deck. The model is alive — it changes as evidence arrives, and it propagates those changes across the portfolio graph.
Connect AI Agents via MCP
Tell operations can be exposed as MCP tools, giving AI agents the ability to read strategic context and write evidence. A Tell-compatible agent doesn't just do things — it does the right things.
Example: Agent discovers relevant market signal
// Agent reads the strategic model
const portfolio = await tell_read_portfolio({
portfolio_id: "portfolio_acme"
});
// Agent finds a relevant assumption
const assumption = portfolio.bets[0].assumptions
.find(a => a.id === "asm_demand");
// Agent submits evidence
await tell_write_evidence({
assumption_id: "asm_demand",
signal: "supports",
content: "LinkedIn campaign generated 47 demo
requests from DACH region in 2 weeks",
confidence: "high",
source: "agent"
});The agent doesn't need to understand the full strategic context. It just needs to know which assumptions to monitor and how to submit evidence when it finds something relevant.
Sync to the Cloud
Your portfolio lives locally in .tell/ — but you can push it to an Apophenic platform instance to share it with your team, view it on a visual canvas, and keep it synced across devices.
Push your portfolio to the cloud
# Authenticate with the platform $ tell auth login # Add a remote $ tell remote add origin https://app.apophenic.com # Push your portfolio $ tell push # Later, pull updates from the platform $ tell pull
Your portfolio lives locally, the platform is your remote. Push and pull keeps them in sync — so your team always has the latest strategic state.
Choose Your Conformance Level
Tell scales with your needs. Start with what you need today and grow into more capability over time.
Reader
You can parse and display Tell models. Good for dashboards, governance views, and reporting tools that consume strategic data without modifying it.
Writer
You can read and write. Append evidence, update statuses, increment versions. This is the level most agent integrations and collaboration tools should target.
Platform
The full experience — real-time events, version history, scenario modelling, and confidence scoring. Apophenic is the canonical Level 3 implementation.