> ## Documentation Index
> Fetch the complete documentation index at: https://docs.armature.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# How Armature works

> From scattered tool calls to replayable, scored sessions

Without instrumentation, agent traffic looks like disconnected tool-call logs: `list_customers`, `send_invoice 402`, a retry, silence. You can't tell who wanted what, whether they got it, or why they left. Armature rebuilds the story.

## The SDK observes, your server behaves the same

The SDK wraps your MCP server. It doesn't proxy traffic, change responses, or add latency to your tools — it records each call as it happens and posts events to Armature off the request path. If the analytics backend is unreachable, your server doesn't notice.

## Agents report intent as they work

The interesting part: the SDK adds a few optional, well-described fields to each tool's input schema — `user_intent`, `agent_thinking`, `user_turn`, `user_frustration`. Modern agents read tool schemas carefully and fill these in as they call your tools. The SDK strips the fields out **before your handler runs**, records them, and passes clean arguments through.

That's how a session shows *"user wants to bulk-refund March invoices"* next to the calls — the agent told us, in flight. Agents that ignore the fields still produce complete sessions. See [What the SDK captures](/sdks/telemetry) for the exact schema.

## Sessions are rebuilt and scored

Events stream into your workspace, where Armature:

1. **Rebuilds sessions** — tool calls are grouped by MCP session and ordered into a conversation: user turns, agent thinking, calls, results.
2. **Scores outcomes** — once a session goes idle, a judge model reads it end-to-end and scores whether the user got what they asked for: **Succeeded**, **Partial**, or **Failed**, with the evidence attached. Pass rate on the dashboard is successful ÷ judged sessions.
3. **Groups use cases** — every session's intent is embedded and clustered. Recurring intents become named [use cases](/dashboard/use-cases) ranked by volume and success rate — including demand you don't support yet.
4. **Surfaces issues** — failing sessions yield concrete problem statements ("search misses 'refund' phrasing"), which are clustered by root cause into [issues](/dashboard/issues) ranked by how many sessions they affect. An issue that stops recurring for three weeks auto-archives.

## Privacy is built into the pipeline

Detection models scan incoming sessions and redact PII and secrets before anything reaches storage. Previews are truncated at the SDK, actor identities are hashed on your server, and secret-shaped values are rejected at the boundary. Details in [Privacy & security](/security/privacy).

## Where the answers show up

* The [dashboard](/dashboard/overview): Overview, Use cases, Issues, Sessions.
* Your coding agent, via the [Armature MCP](/armature-mcp/connect) — the same analytics as read-only MCP tools.