---
title: "Explain policy evaluation for the protection card"
method: POST
path: "/protection/agent/{agent_id}/explain"
tags: ["Protection"]
---

# Explain policy evaluation for the protection card

`POST /protection/agent/{agent_id}/explain`

## Request

- Base URL: `https://api.mnemom.ai/v1`
- URL: `https://api.mnemom.ai/v1/protection/agent/{agent_id}/explain`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Mnemom-Api-Key`
  - API key in cookie `mnemom_session`

Calls the policy engine in dry-run mode against the agent's composed protection card and returns a structured trace + care-framed remediations. Optional `enrich: true` runs an LLM pass over the structured remediations to produce long-form prose; off by default. Read-style POST — no state mutation, no Idempotency-Key.

This endpoint returns a deferred Phase-5 stub (`trace: null`) — the dedicated protection evaluator has not landed, so no policy evaluation runs and no request field is required. `request_snippet.tool_name` is accepted and ignored today; when the evaluator lands it becomes REQUIRED with a **400** `missing_tool_name`, as on the alignment explain (MNE-5820).

## Path parameters

- `agent_id` string, required

## Request body

- object
  - `turn_id` string: Optional — bind to a specific gateway turn.
  - `request_snippet` object: The tool call to explain. Optional and currently ignored — this endpoint returns a Phase-5 stub before any evaluation runs. Becomes required when the protection evaluator lands (MNE-5820).
    - `tool_name` string: A TOOL IDENTIFIER — the name a runtime invokes (`Read`, `Grep`, `Bash`), matched against `capabilities.<name>.tools[]`. NOT a card action (`code_read`, `inference`, `tool_use`); those live in `autonomy.bounded_actions` and never match here.
    - `tool_args` object
  - `enrich` boolean: When true, runs an LLM pass over the structured remediations. Off by default.

## Response `200`

Policy evaluation trace + remediations.

- object
  - `ok` true, required
  - `resource` 'protection', required
  - `trace` object, nullable: EvaluationResult from @mnemom/policy-engine. Null for protection in V1.
  - `reasoning` string, required: Care-framed prose summary.
  - `suggested_remediations` object[], required
    - `for` 'violation' | 'warning' | 'card_gap', required
    - `index` integer, required
    - `remediation` string, required
    - `method` string
    - `url` string
  - `enriched` boolean, required: True when the LLM enrichment ran.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `404`: Resource not found
- `429`: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
- `500`: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.

---

[API](https://skmtc.dev/mnemom/apis/mnemom-api.md) · [All operations](https://skmtc.dev/mnemom/apis/mnemom-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemom/apis/mnemom-api/revisions/274b7a6ea182?raw)