# Deep insights: stored tool-call fields (opt in)

By default Telltale receives no content from your MCP server or API: tool names, routes, outcomes, timings and the IDs your `identify` function returns. That stays true until you turn Deep insights on.

Deep insights lets you see what agents actually asked for. You name the fields Telltale may keep, per MCP tool or per API route. Telltale shows them in the session drawer as **Captured fields (Deep insights)**.

It is **off by default** in three places, and all three must agree before anything is stored:

1. **The workspace owner turns it on** for one site in **Settings › Data & privacy › Deep insights**. The change is recorded in the audit log. Deep insights is part of the Growth and Enterprise plans, and is always available when plans are off (local and self-hosted). On a plan without it (a trial that ended), nothing new is stored and the fields already stored stay readable until they expire.
2. **Your SDK lists the fields** for each tool or route. Anything you don't list never leaves your server.
3. **Telltale tells your SDK the site has it on.** The SDK checks `GET /api/v1/deep-insights` when it starts and reads the answer to every batch. Until it hears "on", it sends nothing.

## What is never stored

These are dropped in your SDK and dropped again when they reach Telltale, **whatever your allowlist says**:

- headers of any kind, cookies and `Set-Cookie`, `Authorization` values;
- fields whose name looks like a credential: token, access/refresh/ID token, password, passphrase, passcode, secret, client secret, API key, access key, private key, credentials, JWT, CSRF/XSRF, session ID, signature, one-time code, MFA, card number, CVV/CVC, SSN, PIN;
- values that look like a credential, anywhere in the value ("Authorization: Bearer …" inside a note counts): `Bearer …`, `Basic …`, JWTs, `sk_live_`/`sk_test_` and `sk-` style keys, Telltale keys, GitHub and Slack tokens, AWS access key IDs, private keys, and `password=…`, `api_key: …`, `secret=…` style assignments.

Nested objects are never captured whole: you list the leaf fields you want (`filters.status`). Free-text tool results (`content` text blocks) are never a source; on MCP only `structuredContent` fields can be listed.

## Limits

- Each value: a string, number, boolean or null, or a list of up to 20 of them. Strings are cut at 1,000 characters.
- Each call: at most 20 fields and 8 KB.
- Kept for **7 days** by default. The owner can choose 7, 14 or 30 days. Then the capture is deleted.
- Stored encrypted (AES-256-GCM with a key used for nothing else).
- On the API, only calls that showed AI agent evidence carry a capture, and Telltale stores captures only for calls it records as AI agent calls. Calls from people's browsers and other traffic are never captured.
- Turning Deep insights off deletes every stored capture for the site at once.
- Erasing a user or account removes their captures, and a subject export includes them with their values.

## MCP servers

`telltale-mcp.js` is the MCP adapter downloaded from https://app.trytelltale.dev/adapters/v1/mcp.js, as [Telltale for MCP servers](/docs/mcp#install) shows (its SHA-256 is on [Server adapters](/docs/server-adapters)).

```javascript
import { createTelltale } from './telltale-mcp.js';
const telltale = createTelltale({
  endpoint: 'https://app.trytelltale.dev',
  serverKey: process.env.TELLTALE_SERVER_KEY,
  identify: ({ authInfo }) => ({ accountId: authInfo?.extra?.accountId }),
  deepInsights: {
    tools: {
      search_orders: { arguments: ['query', 'filters.status'], result: ['count'] },
    },
    // Optional, runs last, before anything is sent. It may remove or shorten fields, never add them.
    redact: (fields, { tool }) => ({ ...fields, 'arguments.query': fields['arguments.query']?.slice(0, 80) }),
  },
});
```

Field keys are `arguments.<path>` and `result.<path>`.

## APIs

`telltale-api.js` is the API middleware downloaded from https://app.trytelltale.dev/adapters/v1/api.js, as [Telltale for APIs](/docs/api-channel#install) shows.

```javascript
import { createTelltaleApi } from './telltale-api.js';
const telltale = createTelltaleApi({
  endpoint: 'https://app.trytelltale.dev',
  serverKey: process.env.TELLTALE_SERVER_KEY,
  deepInsights: {
    routes: {
      'POST /v1/invoices': { body: ['amount', 'currency'], query: ['expand'] },
    },
    // Express and Fastify parse req.body for you. With Next.js or Hono, hand the parsed body over yourself:
    // read: req => ({ body: req.parsedBody }),
    redact: (fields, { route }) => fields,
  },
});
```

Field keys are `body.<path>` and `query.<name>`. Headers are never a source.

## Where it shows

Open an MCP or API session from Sessions, an account card or a stuck point. Each call that has a capture shows **Captured fields (Deep insights)** under its tool or route, with each field's name and value as plain text.

## Your privacy notice

Captured fields can hold what your customers typed into an agent. Tell them in your privacy notice before you turn Deep insights on; the dashboard asks you to confirm that. Telltale processes the fields as your processor, like the rest of your data (see [data location and retention](/docs/data-retention)).

## Related

- [The why field](/docs/mcp#the-why-field-opt-in-per-tool): a one-line reason an agent may give per MCP tool, also opt in.
- [Data stays with you](/docs/mcp#data-stays-with-you): send full content to your own logs or OpenTelemetry instead; Telltale never receives it.
- [Redaction controls](/docs/redaction#mcp-servers-and-apis).