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

# 0099 — One action risk scale, L0 to L4, with derived MCP hints and effect tags; change risk is R0 to R3

> Accepted · 2026-10-19

## Context

The two AI planning documents use five different risk scales between them. Actions ([0098](/adr/0098-actions-are-the-unit)),
approval, AI exposure and the gen validation pass all need a single scale, so that one rule can decide, for example, whether
an agent can call an action without a human. MCP tools carry their own annotation hints, which clients use to warn users. The
SDLC plan has a separate scale for how risky a code change is, which must not be confused with this one.

## Decision

1. **Every action declares one risk level**:

   | Level | Meaning |
   | - | - |
   | L0 | Informational: no data read beyond public context |
   | L1 | Read |
   | L2 | Reversible write |
   | L3 | Financial |
   | L4 | Privileged or destructive |

2. **Effects are tags, separate from the level**: `financial`, `security`, `pii`, `external-communication` and
   `irreversible`. Policies, approvals and evidence can filter on them. A new tag is added by amending this ADR.

3. **MCP tool hints are derived, never hand-written.** When an action is exposed as a tool, gen sets `readOnlyHint` (L0–L1),
   `destructiveHint` (L4, or the `irreversible` tag), `idempotentHint` (the action declares idempotency) and `openWorldHint`
   (the `external-communication` tag).

4. **The level and the tags are the only risk inputs to approval and AI exposure rules.** Other scales in source documents are not used.

5. **Code-change risk is a different scale, named "change risk", R0 to R3**, defined in
   [0120](/adr/0120-sdlc-spec-location-lanes-and-change-risk). The two scales never share a letter or a name.

## Consequences

* One vocabulary across actions, policies, approvals, MCP clients and evidence.
* Choosing a level is a reviewable line on every action. A wrong level is a security finding.
* An MCP client's warning can never disagree with the server's own level, because both come from one declaration.

## Enforcement

Planned: the gen validation pass rejects an action without a level, a destructive or `irreversible` action marked below L4,
and a hand-written MCP hint. Nothing checks this today.

## Supersedes and sources

Supersedes: none. Sources: recommendation by the coordinating agent, 2026-10-19; accepted by the owner with MCP hints and
effect tags (Round 11 R1), and the change-risk name (R2). Informational: the AI Implementation Standard and the Stackra
AI-driven architecture plan, whose scales this replaces.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.