---
title: Scope reads
description: "Plain-English summaries of gaps, decisions, goals, risks, insights, evidence, intents, and contradictions."
---

Eight top-level methods give you focused projections of the current belief state. Each returns a flat `Summary[]` — pre-shaped lists ready to render in a UI without further processing or normalization. Raw underlying scores live under each summary's optional `internals` field for power users; the default shape stays free of engine jargon.

All eight share the same option base — `agentId`, `limit`, `since` — plus per-method filters where relevant.

| Method | Returns | Per-method filter |
|--------|---------|-------------------|
| `beliefs.gaps(opts?)` | `GapSummary[]` | `priority?: 'low' \| 'medium' \| 'high'` |
| `beliefs.decisions(opts?)` | `DecisionSummary[]` | — |
| `beliefs.goals(opts?)` | `GoalSummary[]` | — |
| `beliefs.risks(opts?)` | `RiskSummary[]` | — |
| `beliefs.insights(opts?)` | `InsightSummary[]` | — |
| `beliefs.evidence(opts?)` | `EvidenceSummary[]` | `beliefId?: string` |
| `beliefs.intents(opts?)` | `IntentSummary[]` | — |
| `beliefs.contradictions(opts?)` | `ContradictionSummary[]` | `severity?: 'low' \| 'medium' \| 'high'` |

## Quickstart

```ts
const gaps = await beliefs.gaps({ priority: 'high', limit: 5 })
const risks = await beliefs.risks()
const recentEvidence = await beliefs.evidence({ since: '2026-04-01T00:00:00Z' })

for (const gap of gaps) {
  console.log(`[${gap.priority}] ${gap.summary}`)
  if (gap.suggestion) console.log(`  → ${gap.suggestion}`)
}
```

## Common options

| Option | Type | What it does |
|--------|------|--------------|
| `agentId` | `string` | Restrict to a single agent's contributions. Defaults to the SDK's bound `agent`. |
| `limit` | `number` | Cap returned items. Server applies its own cap if you don't specify. |
| `since` | `string` | ISO timestamp. Filter items at-or-after this time. |
| `signal` | `AbortSignal` | Abort the request mid-flight. |

## Summary shapes

Every summary follows the `Summary<T>` template: `id`, plain-English `summary`, optional `suggestion`, optional `relatedBeliefs`, plus type-specific fields. Internals are opt-in.

### `GapSummary`

```ts
{
  id: string
  summary: string
  priority: 'low' | 'medium' | 'high'
  openSince: string                       // ISO timestamp
  suggestion?: string
  relatedBeliefs?: string[]
  internals?: { rawConfidence?: number; evidenceWeight?: number }
}
```

The priority inversion is intentional: a *low*-confidence gap means the agent has little evidence either way, so the question is wide open and worth investigating — that gets `priority: 'high'`. A *high*-confidence gap means the agent is close to resolving it on its own, so the priority drops.

### `DecisionSummary`

```ts
{
  id: string
  summary: string
  status: 'tentative' | 'committed' | 'reversed'
  decidedAt: string
  commitment: 'loose' | 'firm' | 'revoked'
  suggestion?: string
  relatedGoals?: string[]
  relatedBeliefs?: string[]
}
```

Distinct from `moves.list()` (recommendations) and `trace()` (audit log). Decisions are committed intent: "I will do X."

### `EvidenceSummary`

```ts
{
  id: string
  summary: string
  observedAt: string
  source: string                          // agent or source identifier
  direction: 'supports' | 'contradicts' | 'neutral'
  strength: 'weak' | 'medium' | 'strong'
  relatedBeliefs?: string[]
}
```

`strength` is derived from how much this observation shifted the belief — the engine's reading of "how meaningful was this observation."

### `IntentSummary`

```ts
{
  id: string
  summary: string
  kind: 'goal' | 'decision' | 'constraint'
  status: 'active' | 'completed' | 'abandoned' | 'tentative' | 'committed' | 'reversed' | 'relaxed' | 'removed'
  activeSince: string
  progress?: number                       // 0–1, mostly for goals
  confidence?: 'low' | 'medium' | 'high'  // mostly for decisions
  relatedBeliefs?: string[]
  relatedGoals?: string[]
}
```

The unified shape across all three intent kinds. Filter by `kind` client-side, or use `goals()`/`decisions()` for kind-specific shapes.

### `GoalSummary`

```ts
{
  id: string
  summary: string
  status: 'active' | 'completed' | 'abandoned'
  activeSince: string
  progress?: number                       // 1 if completed, 0 if abandoned
  relatedBeliefs?: string[]
}
```

### `RiskSummary`

```ts
{
  id: string
  summary: string
  severity: 'low' | 'medium' | 'high'         // impact if it occurs
  likelihood: 'low' | 'medium' | 'high' | 'certain'
  identifiedAt: string
  suggestion?: string
  relatedBeliefs?: string[]
}
```

For an expected-impact ranking, map both labels to numbers (e.g. `low: 1, medium: 2, high: 3, certain: 4`) and sort by their product. Both fields are categorical labels in the summary shape; the `internals` field carries the underlying numeric scores if you need them.

### `InsightSummary`

```ts
{
  id: string
  summary: string
  kind: 'contradiction' | 'missing_evidence' | 'ambiguity' | 'leap'
  status: 'active' | 'acknowledged' | 'dismissed'
  relatedBeliefs: string[]
  severity: 'low' | 'medium' | 'high'
  createdAt: string
  suggestion?: string
}
```

Output from the clarity detector — these are *meta*-observations about the belief state itself, not beliefs.

### `ContradictionSummary`

```ts
{
  id: string
  summary: string
  severity: 'low' | 'medium' | 'high'
  beliefs: [string, string]               // pair of belief IDs in conflict
  suggestion?: string
  detectedAt?: string
}
```

The pair is unordered semantically — `beliefs[0]` and `beliefs[1]` are both implicated.

<Callout type="info" title="Auth">
All eight methods require `apiKey` or `scopeToken` auth. `serviceToken` callers are rejected. See [Auth](/dev/sdk/auth).
</Callout>