Skip to main content
Glama

Fairquery Agent Trust & Data Safety

Fortress Shield: restore placeholders with original values (free, on this Worker)

pii_restore_text
Read-onlyIdempotent

WHAT: Fortress Shield (agent I/O PII protection). Put the original values back into texts (typically an LLM answer) that contain placeholders such as [EMAIL_k7q2m9xp4a], by opening meta.sealed_map from pii_redact_text on this Worker (or a legacy clear-text placeholder map). Numeric JSON sentinels are restored only in the redacted document they came from, matched by those bytes in any order. A different document is not rewritten. Slots for a document you did not pass are reported as JSON_NUMBER_DOC_MISMATCH. schema_range_preserved is false. WHEN: After an LLM or third party answered a prompt you sanitized with pii_redact_text (redactionStyle "placeholder"), right before showing the answer to the user. WHEN NOT: To redact (pii_redact_text) or find PII (pii_scan_text). Masked and hashed values cannot be restored; only placeholder style is reversible. COST: Free; no token. RETURNS: One "restored_document" row per text with restored, output_text, replacements, fuzzy_restored, unknown_placeholders and near_miss_placeholders. meta.restore_gate is RESTORE_KEY_OK, or RESTORE_KEY_REQUIRED / RESTORE_KEY_MISMATCH / RESTORE_LIMIT_REACHED, in which case nothing is substituted: restored is false, replacements 0, output_text is the input unchanged and sealed_replacements_withheld only counts them. restored is true only when at least one placeholder was actually replaced. Every row carries map_source ("sealed" | "plaintext"), verified (true only for an authenticated sealed map) and exact (no fuzzy, unknown or near-miss placeholders); meta.verification and meta.audit (counts) summarise them. A clear-text placeholderMap alone is refused on deployments with a seal key (meta.restore_gate SEALED_MAP_REQUIRED, nothing substituted, plaintext_replacements_refused counts). Further gate codes (counts only): TENANT_MISMATCH (map bound to another tenantId), USER_ONLY_RESTORE (restoreAudience "user" without the X-FQ-PII-User-Present header), APPS_RESTORE_REQUIRED (operator requires a user-facing MCP Apps / UI restore). meta.seal_ttl {expires_at, remaining_seconds}; meta.sealed_map_extended with extendTtlHours; meta.receipt with returnReceipt. Errors: INPUT_TOO_LARGE, MAP_MISSING, SEALED_MAP_INVALID (altered or from another deployment), SEALED_MAP_EXPIRED, SEAL_KEY_NOT_CONFIGURED. BEHAVIOR: Original values come back only when the request carries the same restore key header (X-FQ-PII-Restore-Key, configured by the operator in the MCP client connection, never a tool argument) that was present when the map was sealed, and at most maxRestores times per map; otherwise counts only. Holding the sealed map alone is not enough. Runs on this Fairquery-hosted Worker (Cloudflare), not on the caller's machine; inputs leave the client. This Worker's code is designed not to store inputs, results, or an Apify token. No further network call; the map is not forwarded. Milliseconds. Max 50 texts, 200,000 chars each, 500,000 total; map up to 10,000 entries. PARAMETERS: sealedMap: pass meta.sealed_map unchanged (preferred). placeholderMap: legacy clear-text map, honoured only when this deployment has no seal key (or the operator restore policy is "open"), and then marked verified false; if both are given, sealedMap is used alone and placeholderMap is ignored (never merged; PLAINTEXT_MAP_IGNORED note). Every key is replaced wherever it occurs exactly (longest first, one pass, so a restored value is never replaced again). fuzzyRestore (default true): a placeholder the LLM rewrote but whose random id is intact ("EMAIL_k7q2m9xp4a" without brackets, lower case, a space instead of _) is restored too and listed in fuzzy_restored. unknown_placeholders lists exact [TYPE_N] shapes the map does not contain; near_miss_placeholders lists mangled shapes ("EMAIL_3", "[Email_4]") that matched no key; both stay as they are. When restored is true the output contains the ORIGINAL sensitive values: show it to the user, do not send it back to the LLM. limit/offset page whole documents (default 10 per page). EXAMPLE: {"texts":["I will email [EMAIL_t7c3pz2wqa] today."],"sealedMap":"fqs2.…"} with the restore key header -> output_text "I will email jane@acme.com today.", replacements 1; without it -> restored false, sealed_replacements_withheld 1.

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": {
      "texts": "<texts>"
    },
    "name": "pii_restore_text"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoOptional page size: items to return, integer 1-50 (default 10). Example: 10
textsYesRequired. 1-50 documents (prompt, chat message, log, file content), each <= 200,000 chars, total <= 500,000 chars. Example: ["Mail jane@acme.com, key AKIAIOSFODNN7EXAMPLE"]
offsetNoOptional zero-based number of items to skip, integer 0-1000000 (default 0); pass nextOffset from the previous response, e.g. 100
tenantIdNoOptional. Tenant of a tenant-bound sealed_map (pii_redact_text tenantId); a different or missing tenant -> TENANT_MISMATCH, counts only. The X-FQ-PII-Tenant header wins.
sealedMapNoOptional (this or placeholderMap required). meta.sealed_map from pii_redact_text, unchanged. Example: "fqs2.…"
fuzzyRestoreNoOptional boolean, default true. Also restore rewritten placeholders whose random id is intact; false = exact keys only.
returnReceiptNoOptional, default false. true adds meta.receipt, an fqrc2 Ed25519 JWS {map id, restores used, documents, replacements} with an HMAC commitment of these input texts (not an unsalted sha256), detector version, and exp. The restored text is not hashed, because it contains the original values. Default expiry is 30 days (receiptTtlDays). No values; verify with pii_verify_receipt.
extendTtlHoursNoOptional integer 1-720. After an allowed restore, also return meta.sealed_map_extended: the same map (same id, restore count, bindings) re-sealed to expire this many hours from now. Refused (EXTEND_TTL_REFUSED note) when the restore gate refused.
placeholderMapNoOptional, legacy (this or sealedMap required). Object placeholder -> original value, as returned in meta.placeholder_map (deprecated) or placeholder_map by pii_guard_documents; keys 1-200 chars, values <= 10,000 chars, <= 10,000 entries. Example: {"[EMAIL_1]":"jane@acme.com"}
receiptTtlDaysNoOptional integer 1-3650, default 30. Restore-receipt validity in days from now.
restoreAudienceNoOptional, "any" | "user", default "any". "user" = this restore is for the user only: originals come back only with the X-FQ-PII-User-Present header (MCP Apps / client UI), else USER_ONLY_RESTORE, counts only.any

Output Schema

NameRequiredDescriptionDefault
metaNoTool-specific context (summary counts, cost notes, ...)
countYesNumber of items in this page
itemsYesResult rows for this page
totalYesTotal items before paging
offsetYesOffset of the first item in this page
hasMoreYesTrue if more items exist after this page
nextOffsetYesOffset to pass for the next page, or null

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / returnReceipt / description
      Previous value: -"Optional, default false. true adds meta.receipt, an fqrc2 Ed25519 JWS {map id, restores used, documents, replacements} with sha256 of these input texts and exp. Default expiry is 30 days (receiptTtlDays). No values; verify with pii_verify_receipt."New value: +"Optional, default false. true adds meta.receipt, an fqrc2 Ed25519 JWS {map id, restores used, documents, replacements} with an HMAC commitment of these input texts (not an unsalted sha256), detector version, and exp. The restored text is not hashed, because it contains the original values. Default expiry is 30 days (receiptTtlDays). No values; verify with pii_verify_receipt."
  2. Changed2 schema fields changed
    • addedInput schema / properties / receiptTtlDays
      Added value: +{
      +  "default": 30,
      +  "description": "Optional integer 1-3650, default 30. Restore-receipt validity in days from now.",
      +  "maximum": 3650,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • changedInput schema / properties / returnReceipt / description
      Previous value: -"Optional boolean, default false. true adds meta.receipt: HMAC-signed {map id, restores used, documents, replacements, time} (no values); verify with pii_verify_receipt."New value: +"Optional, default false. true adds meta.receipt, an fqrc2 Ed25519 JWS {map id, restores used, documents, replacements} with sha256 of these input texts and exp. Default expiry is 30 days (receiptTtlDays). No values; verify with pii_verify_receipt."
  3. Changed4 schema fields changed
    • addedInput schema / properties / extendTtlHours
      Added value: +{
      +  "description": "Optional integer 1-720. After an allowed restore, also return meta.sealed_map_extended: the same map (same id, restore count, bindings) re-sealed to expire this many hours from now. Refused (EXTEND_TTL_REFUSED note) when the restore gate refused.",
      +  "maximum": 720,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / restoreAudience
      Added value: +{
      +  "default": "any",
      +  "description": "Optional, \"any\" | \"user\", default \"any\". \"user\" = this restore is for the user only: originals come back only with the X-FQ-PII-User-Present header (MCP Apps / client UI), else USER_ONLY_RESTORE, counts only.",
      +  "enum": [
      +    "any",
      +    "user"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / returnReceipt
      Added value: +{
      +  "default": false,
      +  "description": "Optional boolean, default false. true adds meta.receipt: HMAC-signed {map id, restores used, documents, replacements, time} (no values); verify with pii_verify_receipt.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / tenantId
      Added value: +{
      +  "description": "Optional. Tenant of a tenant-bound sealed_map (pii_redact_text tenantId); a different or missing tenant -> TENANT_MISMATCH, counts only. The X-FQ-PII-Tenant header wins.",
      +  "pattern": "^[A-Za-z0-9._:-]{1,128}$",
      +  "type": "string"
      +}
  4. Changed1 schema field changed
    • changedInput schema / properties / sealedMap / description
      Previous value: -"Optional (this or placeholderMap required). meta.sealed_map from pii_redact_text, unchanged. Example: \"fqs1.…\""New value: +"Optional (this or placeholderMap required). meta.sealed_map from pii_redact_text, unchanged. Example: \"fqs2.…\""
  5. Changed4 schema fields changed
    • addedInput schema / properties / fuzzyRestore
      Added value: +{
      +  "default": true,
      +  "description": "Optional boolean, default true. Also restore rewritten placeholders whose random id is intact; false = exact keys only.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / placeholderMap / description
      Previous value: -"Required. Object placeholder -> original value, as returned in meta.placeholder_map by pii_redact_text (or placeholder_map by pii_guard_documents); keys 1-200 chars, values <= 10,000 chars, <= 10,000 entries. Example: {\"[EMAIL_1]\":\"jane@acme.com\",\"[PHONE_1]\":\"+14155550100\"}"New value: +"Optional, legacy (this or sealedMap required). Object placeholder -> original value, as returned in meta.placeholder_map (deprecated) or placeholder_map by pii_guard_documents; keys 1-200 chars, values <= 10,000 chars, <= 10,000 entries. Example: {\"[EMAIL_1]\":\"jane@acme.com\"}"
    • addedInput schema / properties / sealedMap
      Added value: +{
      +  "description": "Optional (this or placeholderMap required). meta.sealed_map from pii_redact_text, unchanged. Example: \"fqs1.…\"",
      +  "maxLength": 4000000,
      +  "minLength": 10,
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "texts",
      -  "placeholderMap"
      -]New value: +[
      +  "texts"
      +]
  6. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds a wealth of context beyond them: the restore key header requirement (never a tool argument), per-map maxRestores limits, tenant binding, seal TTL, that inputs leave the client and run on a Cloudflare Worker, millisecond latency, and the explicit warning not to send restored output back to the LLM. The main deduction is that a large share of the text enumerates return-value gate codes that the existing output schema already covers, diluting the behavioral content.

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

Conciseness3/5

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

Strong front-loading and clear WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE headers make it navigable. However, the RETURNS block is very long and enumerates gate codes and per-row fields that duplicate the output schema, which is padding rather than information an agent needs to select or invoke the tool.

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

Completeness5/5

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

For an 11-parameter tool with nested objects and an output schema, the definition covers everything an agent needs: required inputs, error codes, cost, limits (50 texts, 200k chars each, 500k total), auth prerequisites, and a worked example covering both the success and withheld paths.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by stating precedence rules the schema does not: sealedMap takes priority over placeholderMap, they are never merged, and placeholderMap is only honoured when no seal key exists. It also explains fuzzyRestore's matching behavior with concrete examples and that limit/offset page whole documents rather than slicing text.

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 specific verb and resource: putting original values back into texts containing placeholders such as [EMAIL_k7q2m9xp4a], sourced from meta.sealed_map produced by pii_redact_text. It explicitly names the sibling it is not (pii_redact_text for redaction, pii_scan_text for finding PII), so an agent can distinguish it without opening any schema.

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

Usage Guidelines5/5

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

Has dedicated WHEN and WHEN NOT blocks: use it after an LLM or third party answered a prompt sanitized with redactionStyle "placeholder", right before showing the answer to the user; do not use it to redact or scan. It also states the hard exclusion that masked and hashed values cannot be restored.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources