Skip to main content
Glama

pii_restore

Restore plaintext by substituting REDACTED placeholders from a PII session's mapping. Calling this tool authorizes viewing plaintext.

Instructions

Restore plaintext in a text by substituting REDACTED placeholders from a PII session's mapping (Step 100, ADR-100). Explicit authorization semantics: calling this tool is the authorization to view plaintext. Returns ok:false with an error when the session does not exist, the mapping cannot be decrypted (missing or wrong key), or no encryption key is configured.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "session_id": "<session_id>",
      "text": "<text>",
      "confirm": "<confirm>"
    },
    "name": "pii_restore"
  }
}

Input Schema

NameRequiredDescriptionDefault
textYesText containing {{REDACTED:...}} placeholders
confirmYesmandatory acknowledgement that this call mutates state; the tool writes nothing unless it is true (D5-08, D5-12)
session_idYesPII session id, e.g. pii_abc123

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.1.1
    • addedInput schema / properties / confirm
      Added value: +{
      +  "description": "mandatory acknowledgement that this call mutates state; the tool writes nothing unless it is true (D5-08, D5-12)",
      +  "type": "boolean"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "session_id",
      -  "text"
      -]New value: +[
      +  "session_id",
      +  "text",
      +  "confirm"
      +]
  2. First observedv0.1.0

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnly=false, destructive=false, openWorld=false; the description adds genuinely new behavior: the authorization semantics of the call and three concrete failure modes (missing session, undecryptable mapping, no key configured) with an ok:false return. It stops short of describing the success payload or confirming that plaintext leaves the PII boundary, which would be valuable for a privacy-sensitive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded: purpose first, then semantics, then error behavior. The parenthetical '(Step 100, ADR-100)' is internal design-doc noise that costs tokens without helping tool selection, and the error enumeration is slightly run-on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly carries the return-value burden for the failure path (ok:false plus reason). Combined with the annotations and a fully-described 3-param schema, an agent has enough to call it correctly; only the success return shape is left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and all three parameters already carry their own descriptions (including the mandatory confirm acknowledgement and its D5-08/D5-12 rationale). The description adds no parameter-level detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource pair: restore plaintext by substituting {{REDACTED:...}} placeholders using a PII session's mapping. This is clearly distinguishable from the neighboring session-lifecycle tools (pii_sessions, pii_delete_session, pii_rotate_key, pii_purge_sessions), which manage the mapping rather than consume it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a strong context cue — calling it is itself the authorization to view plaintext — which tells the agent this is the deliberate, audited path to plaintext. It does not, however, name alternatives or state when-not (e.g., 'do not call during automated pipelines'), so exclusions are left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.