Understand what agents are trying to do

One switch turns on the two optional readings of what AI agents set out to do on your product. It's off by default, and it stays off until a workspace owner or admin turns it on.

You'll find it in two places: Connect your channels (the MCP server and API steps) and the Understand section on Home. Both show the same switch for the whole workspace.

#What it turns on

• The why field. For the MCP tools you name in the SDK's why option, an agent can say in one sentence why it's calling the tool. Telltale keeps that sentence (at most 280 characters) for 30 days and shows it as "Agent said:" in the account drawer and the session timeline. It's the agent's own words, not a verified fact. See the why field for how to name the tools.
• AI goals. AI summaries: a model picks a goal name for agent sessions from your own tools, actions and routes, such as "Export, download or report on data". With it, each goal's success rate: "Agents tried to export, download or report on data in 42 sessions; 30% didn't work".

Everything these produce is labelled AI summary. The goal name is a model's choice from your list. The success rate counts the goal statuses Telltale measures (what worked, failed, was blocked or held), and sessions with no result yet are left out of the percentage.

#What it never does

• It never changes a verdict, a rule, a confidence band or what is chargeable.
• A person is never given an agent goal: only sessions an AI agent drove, and calls through your MCP server or API from an agent, are summarised.
• The why text is never sent to an AI provider. AI goals send shapes only (tool and route names, outcome words, counts), as AI summaries describes.

#Without an AI provider key

AI goals need a provider key on the Telltale server (TYPESAFE_API_KEY or ANTHROPIC_API_KEY, see Server configuration). Until one is set, the switch turns on the why field only and says goals need the key. Once the key is set, turn the switch off and on again, or turn on AI summaries in Settings › Data & privacy.

#While it's off

A reason your MCP server sends is discarded when it arrives: nothing is stored. Your tools keep working as before.

#Turning it off

One click turns both off. It deletes, straight away:

• every stored "Agent said:" reason for the workspace's sites;
• the stored AI summaries (goal names, grouped problems and flags).

Each change goes in the audit log, with how many reasons and summaries were deleted.

#API

• GET /api/admin/understand?site= answers {enabled, why, goals, configured, canEdit, reasonsKept, reasonDays}.
• PUT /api/admin/understand {"siteId": "...", "enabled": true} turns it on (owners and admins). With "enabled": false it answers with deleted: {reasons, summaries}.