---
title: Trust & tool reliability
description: "Override agent and source trust at runtime, and track which tools produce useful evidence."
---

`beliefs.trust.*` lets the user adjust how much weight an agent or evidence source carries during fusion. Every override is a stated rating `(confidence, strength)` that the engine applies at fusion time — see [behavioral contracts](/dev/internals/contracts) for the predictability guarantee.

## When to use it

- A user disables an agent: set `confidence: 0, strength: 100, lock: true`.
- A user trusts a domain expert agent above the default: `confidence: 0.95, strength: 50`.
- A source category (e.g. social media) should attenuate weight: set on `{ kind: 'source', id: 'social' }`.

Without an override, agents start from the engine's calibrated prior. Overrides replace that prior for the targeted entity only — every other agent and source is unaffected.

## `beliefs.trust.set(target, options)`

Idempotent upsert.

```ts
await beliefs.trust.set(
  { kind: 'agent', id: 'risk-bot' },
  { confidence: 0.4, strength: 25 },
)

// Hard-disable an unreliable source (locked overrides never drift):
await beliefs.trust.set(
  { kind: 'source', id: 'rumor-mill' },
  { confidence: 0.0, strength: 100, lock: true },
)
```

Parameters:

| Field | Type | What it does |
|-------|------|--------------|
| `target.kind` | `'agent' \| 'source'` | Which entity type. |
| `target.id` | `string` | Entity identifier. |
| `options.confidence` | `number` | Mean of the user prior, in `[0, 1]`. |
| `options.strength` | `number` | How sure you are in this rating. Higher = harder for learned data to drift the override. Use **10** for a weak preference (the engine can still adjust based on evidence), **100** for a confident rating, **500** for an immovable position you don't want learning to override. |
| `options.lock` | `boolean` | When `true`, the engine never drifts this rating with newly-learned data. |

Returns the persisted `TrustOverride`.

## `beliefs.trust.list(options?)`

```ts
const all = await beliefs.trust.list()
const agentsOnly = await beliefs.trust.list({ kind: 'agent' })
```

Returns `TrustOverride[]`.

## `beliefs.trust.get(target)`

```ts
const override = await beliefs.trust.get({ kind: 'agent', id: 'risk-bot' })
if (override) console.log(override.confidence, override.strength)
```

Returns `TrustOverride | null` (null when no override exists).

## `beliefs.trust.unset(target)`

Remove an override. The entity reverts to the engine's calibrated prior at the next fusion step.

```ts
const { removed } = await beliefs.trust.unset({ kind: 'agent', id: 'risk-bot' })
```

Returns `{ removed: boolean }`.

## `TrustEntity` and `TrustOverride` shapes

```ts
interface TrustEntity {
  kind: 'agent' | 'source'
  id: string
}

interface TrustOverride {
  entity: TrustEntity
  confidence: number      // [0, 1]
  strength: number        // ≥ 0
  locked: boolean
  updatedAt: string
}
```

<Callout type="info" title="Auth">
The trust namespace requires `apiKey` or `scopeToken` auth. `serviceToken` callers cannot mutate user-scoped trust. See [Auth](/dev/sdk/auth).
</Callout>

<Callout type="tip" title="Validation">
`set()` validates inputs synchronously — `confidence` must be in `[0, 1]`, `strength` must be non-negative, and `target.kind` must be `'agent'` or `'source'`. Invalid inputs throw `TypeError` before any network call.
</Callout>

---

## Tool reliability priors

`beliefs.tools.*` records and reads running estimates of *tool* reliability — distinct from the agent/source trust above. Where trust overrides are user-stated ratings the engine applies at fusion, tool priors are *learned* estimates: the engine tracks, per `(tool, contextClass)` pair, how often each tool produces useful evidence, so the agent can pick the right tool for the job.

<Callout type="warning" title="Disambiguation">
`beliefs.tools.observe(envelope)` is **not** the same as the top-level `beliefs.observe(envelope)`. The top-level method runs the full belief-extraction pipeline on free-form content. `tools.observe` records a single success/failure outcome — orders of magnitude lighter, and only for tool-reliability tracking.
</Callout>

### `beliefs.tools.observe(envelope)`

Record a single tool outcome. Updates the running estimate in place and returns the new summary.

```ts
const prior = await beliefs.tools.observe({
  tool: 'web_search',
  success: true,
  contextClass: 'market-research',
  weight: 1.0,
})

console.log(`web_search rate now ${prior.rate} (${prior.confidence})`)
```

Envelope:

| Field | Type | What it does |
|-------|------|--------------|
| `tool` | `string` | **Required.** Tool identifier. |
| `success` | `boolean` | **Required.** Did the tool produce useful evidence? |
| `contextClass` | `string` | Optional context label (e.g. `'exploratory-research'`). |
| `weight` | `number` | Optional weight (default 1.0). |
| `agentId` | `string` | Override the bound agent. |
| `signal` | `AbortSignal` | Cancellation. |

Returns `ToolPriorSummary`.

### `beliefs.tools.priors(options?)`

List current priors in scope. Filter to narrow.

```ts
// Every prior in scope:
const all = await beliefs.tools.priors()

// Just one tool:
const search = await beliefs.tools.priors({ tool: 'web_search' })

// Tool + context combo:
const filtered = await beliefs.tools.priors({
  tool: 'github_search',
  contextClass: 'code-review',
})
```

Options: `tool?`, `contextClass?`, `limit?`, `agentId?`, `signal?`.

Returns `ToolPriorSummary[]`.

### `ToolPriorSummary`

```ts
{
  id: string
  summary: string
  tool: string
  contextClass: string                 // empty string when uncategorized
  /** Mean success rate, 0–1. */
  rate: number
  confidence: 'low' | 'medium' | 'high' | 'certain'
  /** 90% uncertainty interval on the mean. */
  credibleInterval: { low: number; high: number }
  /** Total observations accumulated. */
  observations: number
  suggestion?: string
}
```

`rate` is "on average, this tool produces useful evidence `rate × 100`% of the time." `confidence` reflects how many observations back the estimate — `low` below 5 observations, `medium` 5–20, `high` 20+. `credibleInterval` narrows as observations accumulate.

<Callout type="tip" title="Using priors to route">
A common pattern: before calling a tool, fetch its prior. If `confidence === 'low'` and `rate < 0.3`, consider an alternative or attach a fallback. After the call, record the outcome with `tools.observe()` so the prior keeps learning.
</Callout>