v0.2 Draft

Tell Protocol Specification

A complete reference for the Tell data model, entities, conformance levels, and integration patterns.

Overview

Tell is an open protocol for encoding strategic intent in a machine-readable format. It defines a standard data model for representing an organisation's strategic portfolio — its bets, assumptions, evidence, connections, scenarios, and contributors — in a way that any system can read from and write to.

The protocol serves a single purpose: to give strategy a format. Just as GAAP gave accounting a standard for reporting finances and OpenAPI gave APIs a standard for describing interfaces, Tell gives strategic intent a standard for encoding what an organisation is betting on and what evidence says about whether those bets are working.

Tell is designed to be useful across a range of implementations — from a simple JSON file on disk to a full real-time strategic intelligence platform. The protocol scales through three conformance levels, each adding capability without breaking compatibility with the level below.

Design Principles

Strategy as Bets Under Uncertainty

Every strategic commitment is modelled as a falsifiable hypothesis, not a plan to execute. Bets carry confidence, lifecycle status, and evidence.

Minimal Core, Extensible Surface

Seven core entities plus a typed extension mechanism. The core is stable; extensions allow domain-specific adaptation.

Evidence is Append-Only

Evidence records are never modified or deleted. Retractions are new records pointing to originals. This preserves the complete evidential history.

Read-Optimised, Write-Append

Agents and dashboards read frequently. Evidence writes are appends. Structural changes (new bets, status changes) are infrequent and version-bumped.

Source-Agnostic Evidence

Human and AI-curated evidence are treated identically at the structural level. Source is recorded for provenance, not for privilege.

Graph Structure

Connections between bets and shared assumptions create a directed graph, not a hierarchy. This enables systemic portfolio reasoning.

Core Entities

Tell defines eight core entities. Together they form a directed graph representing the complete strategic state of an organisation.

Portfolio

The top-level container. A portfolio represents the complete strategic model for an organisation, division, or team.

Field	Type	Note
id	string	Unique identifier
name	string	Human-readable name
organisation	string	Owning organisation
version	integer	Incremented on structural changes
tell_version	string	Protocol version (e.g. "0.2")
bets	Bet[]	Strategic bets in the portfolio
connections	Connection[]	Cross-bet relationships
scenarios	Scenario[]	What-if portfolio branches
contributors	Contributor[]	People and agents

Bet

A falsifiable hypothesis that the organisation is investing resources to test. Every bet carries a thesis, assumptions, and a lifecycle status.

Field	Type	Note
id	string	Unique identifier
title	string	Short descriptive title
thesis	string	The falsifiable hypothesis
status	enum	active \| paused \| killed \| succeeded
stage	enum	exploring \| validating \| committed \| scaling
confidence	integer	0-100, derived or overridden
time_horizon	string	Expected resolution timeframe
owner	string	Accountable contributor
assumptions	Assumption[]	Must have at least 1
created_at	datetime
updated_at	datetime

Assumption

A condition that must be true for a bet's thesis to hold. The many-to-many relationship between assumptions and bets is structurally critical — shared assumptions create cross-bet risk visibility.

Field	Type	Note
id	string	Unique identifier
text	string	The assumption statement
status	enum	holding \| pressure \| failing \| unknown
bet_ids	string[]	Bets this assumption supports
evidence	Evidence[]	Signals for/against
created_at	datetime

Evidence

A discrete signal that informs whether an assumption is holding or breaking. Evidence is immutable once written — retractions are new evidence records pointing to the original.

Field	Type	Note
id	string	Unique identifier
assumption_id	string	The assumption this informs
signal	enum	supports \| weakens \| neutral
content	string	Description of the signal
confidence	enum	high \| medium \| low
source	enum	human \| agent \| integration
contributor_id	string	Who/what submitted
is_retracted	boolean	Default false
superseded_by	string?	ID of retraction record
timestamp	datetime	When the evidence was recorded

Connection

A directed relationship between two bets. Connections make the portfolio a system, not a list — revealing tensions, synergies, and dependencies.

Field	Type	Note
id	string	Unique identifier
from_bet_id	string	Source bet
to_bet_id	string	Target bet
type	enum	tension \| synergy \| dependency \| resource_conflict
status	enum	active \| monitoring \| resolved \| escalated
description	string	Why this connection exists

Scenario

A hypothetical modification to the portfolio — a sandbox for "what if" reasoning without altering the live model.

Field	Type	Note
id	string	Unique identifier
name	string	Descriptive name
description	string	What this scenario explores
status	enum	draft \| explored \| enacted \| rejected
bet_modifications	ScenarioBet[]	Overrides per bet
created_by	string	Contributor who created it

Experiment

A time-boxed, cost-capped test designed to validate or falsify a bet's thesis through targeted assumption testing. Experiments link a bet to specific assumptions with clear success/failure criteria.

Field	Type	Note
id	string	Unique identifier
bet_id	string	The bet being tested
assumption_ids	string[]	Assumptions under test
hypothesis	string	What the experiment tests
method	string	How it will be conducted
success_criteria	string	What constitutes success
failure_criteria	string	What constitutes failure
status	enum	planned \| running \| concluded \| abandoned
cost_ceiling	string	Maximum cost allowed
time_box	string	Maximum duration allowed
outcome	object	signal + summary + concluded_at

Contributor

An entity that reads from or writes to the model. Contributors can be human or agent — the protocol makes no structural distinction.

Field	Type	Note
id	string	Unique identifier
name	string	Display name
type	enum	human \| agent
role	enum	owner \| facilitator \| contributor \| observer
last_active_at	datetime	Most recent interaction

Evidence Model

Evidence is the lifeblood of the Tell protocol. Every evidence record carries three dimensions:

Signal

Does this evidence support, weaken, or have neutral bearing on the assumption?

supports | weakens | neutral

Confidence

How much weight should this evidence carry? Self-assessed by the contributor.

high | medium | low

Source

Who or what produced this evidence? Recorded for provenance, not privilege.

human | agent | integration

Immutability constraint: Evidence records are never modified or deleted. If evidence is found to be incorrect, a new retraction record is created that references the original via superseded_by. This preserves the complete evidential history and audit trail.

Confidence Algorithm

Bet confidence in Tell is derived from evidence, not declared by fiat. The algorithm operates in three steps:

Step 1: Per-Assumption Evidence Score

Each piece of evidence contributes a weighted score based on signal direction, self-assessed confidence, and recency.

signal_weight: supports = +1, weakens = -1, neutral = 0

confidence_mult: high = 1.0, medium = 0.6, low = 0.3

recency_decay: >30d = 0.5x, >90d = 0.25x

score = clamp(50 + (sum_of_contributions × 10), 0, 100)

Step 2: Blend with Status Weight

Evidence score is blended with the assumption's categorical status to produce a final assumption confidence.

with evidence: 0.3 × status_weight + 0.7 × evidence_score

without evidence: status_weight (backwards compatible)

Step 3: Bet Confidence

The bet's confidence is the average of all its assumption blended scores, rounded to the nearest integer. Default: 50 if no assumptions exist.

Conformance Levels

Tell defines three conformance levels. Each builds on the one below. An implementation at any level can interoperate with implementations at other levels.

Level	Name	Capabilities	Example Use Cases
1	Reader	Parse all entities, preserve extensions on round-trip, handle many-to-many relationships	BI dashboards, governance views, reporting
2	Writer	Level 1 + append evidence, increment versions, record audit events, maintain immutability constraint	Agent frameworks, AI curation, collaboration tools
3	Platform	Level 2 + real-time event stream, version history, portfolio diffing, scenario modelling, confidence scoring	Strategic intelligence platforms

MCP Integration

Tell operations are designed to be exposed as MCP (Model Context Protocol) tools, enabling AI agents to read strategic context and write evidence through standard tool calls.

tell_read_portfolio

Returns the complete strategic model with all bets, assumptions, evidence, and connections.

Params: portfolio_id, include_evidence?, include_scenarios?

tell_read_assumption

Returns a specific assumption with its full evidence timeline and linked bets.

Params: assumption_id

tell_write_evidence

Appends a new evidence record to an assumption. Increments portfolio version.

Params: assumption_id, signal, content, confidence, source

tell_read_stale

Returns assumptions with no recent evidence, sorted by staleness.

Params: portfolio_id, days_threshold?

tell_read_risk

Returns assumptions shared across multiple bets where status is under pressure.

Params: portfolio_id

Versioning

Tell portfolios carry an integer version number that increments on structural changes — new bets, status transitions, connection modifications. Evidence appends do not increment the version, as they represent continuous signal accumulation rather than structural change.

Level 3 (Platform) implementations support version history and portfolio diffing — the ability to compare any two versions and see exactly what changed in the strategic model.

Serialisation

The canonical serialisation format is JSON. Tell files use the .tell.json extension.

Every Tell document must include a tell_version field at the top level indicating which version of the protocol it conforms to.

{
  "tell_version": "0.2",
  "portfolio": { ... }
}

Extensions

Every entity supports an optional extensions object for domain-specific data. Extensions use namespaced keys:

tell.* — Reserved for future protocol use
apophenic.* — Platform-specific extensions
<vendor>.* — Third-party extensions

Conformant implementations must preserve unrecognised extensions on round-trip — never strip data you don't understand.

Security & Governance

Tell models contain sensitive strategic information. Implementations must consider:

Access control: Who can read the portfolio? Who can write evidence? Role-based access (owner, facilitator, contributor, observer) is recommended.
Audit trail: All mutations should be recorded with contributor attribution and timestamps.
Agent identity: AI agents should be registered as contributors with explicit role assignments.
Transport security: Tell data should always be transmitted over encrypted channels (TLS).

What's next?

Ready to implement? Start with the Getting Started Guide for a practical walkthrough, or explore the About page to understand the story behind Tell.