Skip to main content
Glama

Fairquery Agent Trust & Data Safety

Fortress Shield: redact PII and secrets (free, on this Worker)

pii_redact_text
Read-onlyIdempotent

WHAT: Fortress Shield (agent I/O PII protection). Return sanitized copies of texts with every local PII/secret finding replaced: placeholder [EMAIL_k7q2m9xp4a] (random id per value), mask, or hash. For placeholders the originals come back only inside meta.sealed_map, an AES-256-GCM encrypted string that this Worker opens in pii_restore_text. The originals stay out of the model context. WHEN: Right before sending user data to an LLM/third party. Keep meta.sealed_map if you need to restore originals in the LLM answer later. WHEN NOT: For a findings report only use pii_scan_text. For unlabelled names (NER) or fetching PDFs and remote documents use pii_guard_documents (paid). http(s) URLs in text you already have are redacted here for free. COST: Free; no token. RETURNS: One "redacted_document" row per text with output_text, typed_placeholders_escaped, context_lowered, context_suppressed, below_threshold, context_report, field_paths (JSON input) and, with failClosed, blocked / block_reasons (output_text null); meta.audit, meta.secret_guidance, meta.compliance, meta.would_fail_closed; meta.sealed_map (placeholder style, "fqs2.…"; null plus a SEAL_KEY_NOT_CONFIGURED note when this deployment has no seal key) and meta.seal {algorithm, entries, expires_at, restore_bound, max_restores}. Errors: INPUT_TOO_LARGE, INVALID_PATTERN, INVALID_ARGUMENT, SEALED_MAP_INVALID, SEALED_MAP_EXPIRED, SEAL_KEY_NOT_CONFIGURED, RESTORE_KEY_REQUIRED / RESTORE_KEY_MISMATCH (priorSealedMap bound to another restore key). BEHAVIOR: Placeholder ids are random on every call unless you pass priorSealedMap; "hash" is random per call unless a hash key is set. The sealed_map is bound to the restore key header of this request (X-FQ-PII-Restore-Key, set by the operator in the client connection); without one, pii_restore_text reports counts only. 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; texts are not forwarded. Milliseconds. PARAMETERS: texts: one element per document, 500,000 chars in total; the same value gets the same placeholder in every document of one call, and case/format variants share it (JANE@ACME.COM and jane@acme.com; +1 415 555 0100 and (415) 555-0100). Placeholder-shaped text already in the input (a user typing "[EMAIL_1]") is itself replaced by a [TYPED_PLACEHOLDER_] placeholder and restored verbatim, so it can never pull another value. priorSealedMap: the meta.sealed_map of an earlier call; values seen before keep their placeholder, new ones are added, and the returned sealed_map covers both (use it across turns and when paging). redactionStyle: "placeholder" is the only reversible style; "mask" keeps a few characters for human review; "hash" with hashKey (16-256 chars, your own key) gives the same output for the same value in every call (HMAC-SHA256, joinable), without hashKey the salt is random per call. sealTtlHours: how long the sealed_map opens (1-720, default 24). returnPlaceholderMap: deprecated and refused unless the request carries the restore key header; use sealed_map. maxRestores: restore cap for this sealed_map (default 3). entityTypes / allowList / allowDomains / allowPatterns / customDetectors / contextScoring / contextMode / entropyScan / defaultPhoneRegion: identical semantics to pii_scan_text. limit/offset page whole documents (one item per text, default 50 = all). EXAMPLE: {"texts":["Call +1 415 555 0100 or mail jane@acme.com"]} -> output_text "Call [PHONE_4hq8m2xk9c] or mail [EMAIL_t7c3pz2wqa]", meta.sealed_map "fqs2.…".

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_redact_text"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoOptional page size: items to return, integer 1-50 (default 50). Example: 50
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
hashKeyNoOptional, hash style only, discouraged. Your own 16-256 char key for deterministic HMAC-SHA256 hashes. As an argument it sits in the model context (HASHKEY_ARG_IN_CONTEXT note); prefer the X-FQ-PII-Hash-Key request header set in the MCP client connection, which wins when both are present. Never returned.
tenantIdNoOptional, 1-128 chars [A-Za-z0-9._:-]. Binds the sealed_map to a tenant (a hash is stored inside the encrypted map); pii_restore_text then opens it only for the same tenant (TENANT_MISMATCH otherwise). The X-FQ-PII-Tenant connection header wins over this argument.
allowListNoOptional, default [] (nothing exempt). 0-500 exact values (<= 500 chars each) that are never flagged; whole-value, case-insensitive match, not substring. Example: ["support@yourco.com","192.0.2.1"]
chunkSafeNoOptional boolean, default false. true treats texts as consecutive chunks of ONE stream (e.g. streamed LLM output): detection runs over the joined stream, so a value split across a chunk boundary ("jane@ac" + "me.com") is still found; its placeholder goes in the chunk where it starts and its tail is removed from the next chunk. meta.chunk_safe {chunks, boundary_findings}.
leakCheckNoOptional boolean, default false. true re-scans every output_text after redaction for residual PII/secrets (anything not produced by this redaction) -> meta.leak_check {passed, residual_types, documents_with_residuals}; with failClosed a leaking document is withheld (LEAK_RESIDUAL).
failClosedNoOptional boolean, default false. true withholds a document (output_text null, blocked true, block_reasons) when a candidate was left in its text: a match dropped by contextMode "drop", or below minConfidence. Without it, meta.would_fail_closed counts such documents.
contextModeNoOptional, "lower" | "drop", default "lower". What happens to a match that only a negative context word argues against: "lower" still flags/redacts it with confidence "low" and context "negative:<reason>" (counted in context_lowered); "drop" (strict precision) leaves it untouched (counted in context_suppressed).lower
detectNamesNoOptional. Omit to keep labelled person names (Dear, Patient, sign-off). false turns those labelled hits off. true keeps them; full person-name NER runs only in the Apify Actor (pii_guard_documents).
entityTypesNoOptional, default omitted = every free-tool detector (pii_list_detectors rows with local:true). 0-40 detector type names (<= 40 chars, case-insensitive), e.g. ["EMAIL","CREDIT_CARD","AWS_ACCESS_KEY"]. Valid values: the "type" field of those rows; unknown names match nothing (no error)
entropyScanNoOptional boolean, default false. true also flags unlabeled random-looking tokens of 20-200 chars as HIGH_ENTROPY_STRING (catches unknown key formats; may flag hashes/UUIDs). Example: true
maxRestoresNoOptional integer 1-100, default 3. How many pii_restore_text calls may return original values for this sealed_map; later calls report counts only (RESTORE_LIMIT_REACHED).
allowDomainsNoOptional, default []. 0-200 email domains whose addresses are never flagged; subdomains included. Example: ["yourco.com"] exempts support@yourco.com and a@eu.yourco.com
sealTtlHoursNoOptional integer 1-720, default 24. Hours until meta.sealed_map stops opening.
allowPatternsNoOptional, default []. 0-50 JavaScript regular expressions (<= 200 chars; no backreferences or nested quantifiers -> INVALID_PATTERN); a finding whose value matches any of them is not flagged. Example: ["^192\.0\.2\.","@example\.(com|org)$"]
minConfidenceNoOptional, "low" | "medium" | "high", default "low" (everything). Findings below this confidence are left in the text and counted per document as below_threshold (types only); combine with failClosed on pii_redact_text to withhold documents that contain them.low
returnReceiptNoOptional boolean, default false. true adds meta.receipt, an Ed25519 compact JWS (fqrc2) over operation, map id, counts, per-type counts, detector version, tenant tag, an HMAC commitment of the input texts (not an unsalted sha256), a sha256 of the redacted output when it changed, and expiry (no original values); check it with pii_verify_receipt on /pii-guard/mcp or offline with pii_list_detectors receipt_verification. Default expiry is 30 days (receiptTtlDays).
surrogateSeedNoOptional, 1-200 chars, redactionStyle "surrogate" only. WARNING: this argument is visible to the model and to transcripts. Prefer the X-FQ-PII-Surrogate-Seed request header (same 512-char cap as the hash key, never echoed). The header wins when both are set. Omit both for a per-call seed. There is no per-tenant isolation. Surrogates cannot be restored.
contextScoringNoOptional boolean, default true. true uses the words around a match: labels like "SSN:", "phone:", "my cell", "call me" raise confidence, and a label earlier on the same line wins over a negative word. "version"/"v" before an IPv4 or phone-shaped number and "invoice"/"order"/"ticket"/"ref" before a bare phone-shaped number lower it (see contextMode). Phones with +country code, parentheses or two separators, and IPv4 with a port, CIDR suffix or 3-digit octet are never lowered. false = format-only scoring.
priorSealedMapNoOptional. meta.sealed_map from an earlier pii_redact_text call (placeholder style only). Keeps the same placeholder for values seen before. Example: "fqs1.…"
receiptTtlDaysNoOptional integer 1-3650, default 30. Receipt validity in days from now.
redactionStyleNoOptional, one of "placeholder" | "mask" | "hash" | "label" | "surrogate", default "placeholder". "placeholder" = [EMAIL_k7q2m9xp4a] (reversible with meta.sealed_map); "mask" = j***@a***.com, **** **** **** 1111; "hash" = [EMAIL:3f2a9c0d1b7e] (salted sha256 prefix; with hashKey an HMAC that stays the same across calls); "label" = type only, [EMAIL]; "surrogate" = a synthetic value of the same shape, prefixed with ⟦SG⟧, stable for the same text and surrogateSeed, and not reversible (other types [TYPE_SURROGATE_id]). Example: "mask"placeholder
customDetectorsNoOptional, default []. 0-20 of your own detectors (regex pattern and/or terms dictionary) for account IDs, ticket formats or member numbers; findings use your type name with category "custom" and are redacted and restored like built-in types.
detectAddressesNoOptional boolean, default false. true also runs the street-address patterns on this Worker (STREET_ADDRESS: house number + street, PO Box, units, trailing city/state/ZIP or postcode; US/UK/FR/DE-style forms). Pattern-based, medium confidence; place-name NER (LOCATION) and person names stay Actor-only. Example: true
restoreAudienceNoOptional, "any" | "user", default "any". "user" marks the sealed_map user-only: pii_restore_text returns originals only on requests with the X-FQ-PII-User-Present header (set by an MCP Apps / client UI action, not by the model); otherwise USER_ONLY_RESTORE, counts only.any
destinationPolicyNoOptional preset for where the text goes: "llm_public" | "llm_private" | "internal" | "logs" | "analytics". It sets minConfidence, contextMode, entropyScan, excludeEntityTypes and (pii_redact_text) failClosed / leakCheck; meta.destination_policy shows what was applied. Omit to use the individual parameters.
defaultPhoneRegionNoOptional, default "US". ISO 3166-1 alpha-2 code (2 letters, pattern ^[A-Za-z]{2}$, case-insensitive) used only for phone numbers written without a +country prefix. Examples: "US", "DE", "GB"US
excludeEntityTypesNoOptional, default []. 0-40 detector type names to switch off (case-insensitive), e.g. ["IP_ADDRESS","POSTAL_CODE"]; applied after entityTypes. customDetectors always run.
returnPlaceholderMapNoOptional boolean, default false. Deprecated: true (placeholder style only) asks for meta.placeholder_map {"[EMAIL_…]":"jane@acme.com"} with the ORIGINAL values in clear text; honoured only when the request carries the operator restore key header or sealing is unavailable (otherwise a PLAINTEXT_MAP_REFUSED note). Prefer meta.sealed_map.

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 / surrogateSeed / description
      Previous value: -"Optional, 1-200 chars. Only used when redactionStyle is \"surrogate\". Same text and same seed always produce the same surrogates. Omit to use the built-in default seed. Surrogates cannot be restored."New value: +"Optional, 1-200 chars, redactionStyle \"surrogate\" only. WARNING: this argument is visible to the model and to transcripts. Prefer the X-FQ-PII-Surrogate-Seed request header (same 512-char cap as the hash key, never echoed). The header wins when both are set. Omit both for a per-call seed. There is no per-tenant isolation. Surrogates cannot be restored."
  2. Changed3 schema fields changed
    • changedInput schema / properties / redactionStyle / description
      Previous value: -"Optional, one of \"placeholder\" | \"mask\" | \"hash\" | \"label\" | \"surrogate\", default \"placeholder\". \"placeholder\" = [EMAIL_k7q2m9xp4a] (reversible with meta.sealed_map); \"mask\" = j***@a***.com, **** **** **** 1111; \"hash\" = [EMAIL:3f2a9c0d1b7e] (salted sha256 prefix; with hashKey an HMAC that stays the same across calls); \"label\" = type only, [EMAIL]; \"surrogate\" = consistent fake value of the same kind (user-x7k2qm@example.invalid, +1-202-555-01xx, 192.0.2.x; other types [TYPE_SURROGATE_id]), not reversible. Example: \"mask\""New value: +"Optional, one of \"placeholder\" | \"mask\" | \"hash\" | \"label\" | \"surrogate\", default \"placeholder\". \"placeholder\" = [EMAIL_k7q2m9xp4a] (reversible with meta.sealed_map); \"mask\" = j***@a***.com, **** **** **** 1111; \"hash\" = [EMAIL:3f2a9c0d1b7e] (salted sha256 prefix; with hashKey an HMAC that stays the same across calls); \"label\" = type only, [EMAIL]; \"surrogate\" = a synthetic value of the same shape, prefixed with ⟦SG⟧, stable for the same text and surrogateSeed, and not reversible (other types [TYPE_SURROGATE_id]). Example: \"mask\""
    • changedInput schema / properties / returnReceipt / description
      Previous value: -"Optional boolean, default false. true adds meta.receipt, an Ed25519 compact JWS (fqrc2) over operation, map id, counts, tenant tag, sha256 of the input texts, and expiry (no values); check it with pii_verify_receipt on /pii-guard/mcp or offline with pii_list_detectors receipt_verification. Default expiry is 30 days (receiptTtlDays)."New value: +"Optional boolean, default false. true adds meta.receipt, an Ed25519 compact JWS (fqrc2) over operation, map id, counts, per-type counts, detector version, tenant tag, an HMAC commitment of the input texts (not an unsalted sha256), a sha256 of the redacted output when it changed, and expiry (no original values); check it with pii_verify_receipt on /pii-guard/mcp or offline with pii_list_detectors receipt_verification. Default expiry is 30 days (receiptTtlDays)."
    • addedInput schema / properties / surrogateSeed
      Added value: +{
      +  "description": "Optional, 1-200 chars. Only used when redactionStyle is \"surrogate\". Same text and same seed always produce the same surrogates. Omit to use the built-in default seed. Surrogates cannot be restored.",
      +  "maxLength": 200,
      +  "minLength": 1,
      +  "type": "string"
      +}
  3. Changed3 schema fields changed
    • addedInput schema / properties / detectNames
      Added value: +{
      +  "description": "Optional. Omit to keep labelled person names (Dear, Patient, sign-off). false turns those labelled hits off. true keeps them; full person-name NER runs only in the Apify Actor (pii_guard_documents).",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / receiptTtlDays
      Added value: +{
      +  "default": 30,
      +  "description": "Optional integer 1-3650, default 30. 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, an HMAC-signed statement (map id, documents, findings, tenant tag, time; no values) that this Worker produced the redaction; check it with pii_verify_receipt on /pii-guard/mcp."New value: +"Optional boolean, default false. true adds meta.receipt, an Ed25519 compact JWS (fqrc2) over operation, map id, counts, tenant tag, sha256 of the input texts, and expiry (no values); check it with pii_verify_receipt on /pii-guard/mcp or offline with pii_list_detectors receipt_verification. Default expiry is 30 days (receiptTtlDays)."
  4. Changed11 schema fields changed
    • addedInput schema / properties / chunkSafe
      Added value: +{
      +  "default": false,
      +  "description": "Optional boolean, default false. true treats texts as consecutive chunks of ONE stream (e.g. streamed LLM output): detection runs over the joined stream, so a value split across a chunk boundary (\"jane@ac\" + \"me.com\") is still found; its placeholder goes in the chunk where it starts and its tail is removed from the next chunk. meta.chunk_safe {chunks, boundary_findings}.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / destinationPolicy
      Added value: +{
      +  "description": "Optional preset for where the text goes: \"llm_public\" | \"llm_private\" | \"internal\" | \"logs\" | \"analytics\". It sets minConfidence, contextMode, entropyScan, excludeEntityTypes and (pii_redact_text) failClosed / leakCheck; meta.destination_policy shows what was applied. Omit to use the individual parameters.",
      +  "enum": [
      +    "llm_public",
      +    "llm_private",
      +    "internal",
      +    "logs",
      +    "analytics"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / excludeEntityTypes
      Added value: +{
      +  "description": "Optional, default []. 0-40 detector type names to switch off (case-insensitive), e.g. [\"IP_ADDRESS\",\"POSTAL_CODE\"]; applied after entityTypes. customDetectors always run.",
      +  "items": {
      +    "maxLength": 40,
      +    "type": "string"
      +  },
      +  "maxItems": 40,
      +  "type": "array"
      +}
    • addedInput schema / properties / failClosed
      Added value: +{
      +  "default": false,
      +  "description": "Optional boolean, default false. true withholds a document (output_text null, blocked true, block_reasons) when a candidate was left in its text: a match dropped by contextMode \"drop\", or below minConfidence. Without it, meta.would_fail_closed counts such documents.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / leakCheck
      Added value: +{
      +  "default": false,
      +  "description": "Optional boolean, default false. true re-scans every output_text after redaction for residual PII/secrets (anything not produced by this redaction) -> meta.leak_check {passed, residual_types, documents_with_residuals}; with failClosed a leaking document is withheld (LEAK_RESIDUAL).",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / minConfidence
      Added value: +{
      +  "default": "low",
      +  "description": "Optional, \"low\" | \"medium\" | \"high\", default \"low\" (everything). Findings below this confidence are left in the text and counted per document as below_threshold (types only); combine with failClosed on pii_redact_text to withhold documents that contain them.",
      +  "enum": [
      +    "low",
      +    "medium",
      +    "high"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / redactionStyle / description
      Previous value: -"Optional, one of \"placeholder\" | \"mask\" | \"hash\", default \"placeholder\". \"placeholder\" = [EMAIL_k7q2m9xp4a] (reversible with meta.sealed_map); \"mask\" = j***@a***.com, **** **** **** 1111; \"hash\" = [EMAIL:3f2a9c0d1b7e] (salted sha256 prefix; with hashKey an HMAC that stays the same across calls). Example: \"mask\""New value: +"Optional, one of \"placeholder\" | \"mask\" | \"hash\" | \"label\" | \"surrogate\", default \"placeholder\". \"placeholder\" = [EMAIL_k7q2m9xp4a] (reversible with meta.sealed_map); \"mask\" = j***@a***.com, **** **** **** 1111; \"hash\" = [EMAIL:3f2a9c0d1b7e] (salted sha256 prefix; with hashKey an HMAC that stays the same across calls); \"label\" = type only, [EMAIL]; \"surrogate\" = consistent fake value of the same kind (user-x7k2qm@example.invalid, +1-202-555-01xx, 192.0.2.x; other types [TYPE_SURROGATE_id]), not reversible. Example: \"mask\""
    • changedInput schema / properties / redactionStyle / enum
      Previous value: -[
      -  "placeholder",
      -  "mask",
      -  "hash"
      -]New value: +[
      +  "placeholder",
      +  "mask",
      +  "hash",
      +  "label",
      +  "surrogate"
      +]
    • addedInput schema / properties / restoreAudience
      Added value: +{
      +  "default": "any",
      +  "description": "Optional, \"any\" | \"user\", default \"any\". \"user\" marks the sealed_map user-only: pii_restore_text returns originals only on requests with the X-FQ-PII-User-Present header (set by an MCP Apps / client UI action, not by the model); otherwise 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, an HMAC-signed statement (map id, documents, findings, tenant tag, time; no values) that this Worker produced the redaction; check it with pii_verify_receipt on /pii-guard/mcp.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / tenantId
      Added value: +{
      +  "description": "Optional, 1-128 chars [A-Za-z0-9._:-]. Binds the sealed_map to a tenant (a hash is stored inside the encrypted map); pii_restore_text then opens it only for the same tenant (TENANT_MISMATCH otherwise). The X-FQ-PII-Tenant connection header wins over this argument.",
      +  "pattern": "^[A-Za-z0-9._:-]{1,128}$",
      +  "type": "string"
      +}
  5. Changed1 schema field changed
    • addedInput schema / properties / detectAddresses
      Added value: +{
      +  "default": false,
      +  "description": "Optional boolean, default false. true also runs the street-address patterns on this Worker (STREET_ADDRESS: house number + street, PO Box, units, trailing city/state/ZIP or postcode; US/UK/FR/DE-style forms). Pattern-based, medium confidence; place-name NER (LOCATION) and person names stay Actor-only. Example: true",
      +  "type": "boolean"
      +}
  6. Changed5 schema fields changed
    • addedInput schema / properties / contextMode
      Added value: +{
      +  "default": "lower",
      +  "description": "Optional, \"lower\" | \"drop\", default \"lower\". What happens to a match that only a negative context word argues against: \"lower\" still flags/redacts it with confidence \"low\" and context \"negative:<reason>\" (counted in context_lowered); \"drop\" (strict precision) leaves it untouched (counted in context_suppressed).",
      +  "enum": [
      +    "lower",
      +    "drop"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / contextScoring / description
      Previous value: -"Optional boolean, default true. true uses the words just before a match: labels like \"SSN:\", \"phone:\", \"call me\" raise confidence; \"version\"/\"v\" before an IPv4 or phone-shaped number and \"invoice\"/\"order\"/\"ticket\"/\"zip\" before a phone-shaped number drop it (meta.documents[].context_suppressed counts them). false = format-only scoring."New value: +"Optional boolean, default true. true uses the words around a match: labels like \"SSN:\", \"phone:\", \"my cell\", \"call me\" raise confidence, and a label earlier on the same line wins over a negative word. \"version\"/\"v\" before an IPv4 or phone-shaped number and \"invoice\"/\"order\"/\"ticket\"/\"ref\" before a bare phone-shaped number lower it (see contextMode). Phones with +country code, parentheses or two separators, and IPv4 with a port, CIDR suffix or 3-digit octet are never lowered. false = format-only scoring."
    • changedInput schema / properties / hashKey / description
      Previous value: -"Optional, hash style only. Your own 16-256 char key for deterministic HMAC-SHA256 hashes, so the same value hashes the same in every call. This Worker uses it for this call only and never returns it."New value: +"Optional, hash style only, discouraged. Your own 16-256 char key for deterministic HMAC-SHA256 hashes. As an argument it sits in the model context (HASHKEY_ARG_IN_CONTEXT note); prefer the X-FQ-PII-Hash-Key request header set in the MCP client connection, which wins when both are present. Never returned."
    • addedInput schema / properties / maxRestores
      Added value: +{
      +  "default": 3,
      +  "description": "Optional integer 1-100, default 3. How many pii_restore_text calls may return original values for this sealed_map; later calls report counts only (RESTORE_LIMIT_REACHED).",
      +  "maximum": 100,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • changedInput schema / properties / returnPlaceholderMap / description
      Previous value: -"Optional boolean, default false. Deprecated: true (placeholder style only) also adds meta.placeholder_map {\"[EMAIL_…]\":\"jane@acme.com\"} with the ORIGINAL values in clear text. Prefer meta.sealed_map."New value: +"Optional boolean, default false. Deprecated: true (placeholder style only) asks for meta.placeholder_map {\"[EMAIL_…]\":\"jane@acme.com\"} with the ORIGINAL values in clear text; honoured only when the request carries the operator restore key header or sealing is unavailable (otherwise a PLAINTEXT_MAP_REFUSED note). Prefer meta.sealed_map."
  7. Changed11 schema fields changed
    • addedInput schema / properties / allowDomains
      Added value: +{
      +  "description": "Optional, default []. 0-200 email domains whose addresses are never flagged; subdomains included. Example: [\"yourco.com\"] exempts support@yourco.com and a@eu.yourco.com",
      +  "items": {
      +    "maxLength": 253,
      +    "minLength": 1,
      +    "pattern": "^@?(?:\\*\\.)?[A-Za-z0-9.-]+$",
      +    "type": "string"
      +  },
      +  "maxItems": 200,
      +  "type": "array"
      +}
    • addedInput schema / properties / allowPatterns
      Added value: +{
      +  "description": "Optional, default []. 0-50 JavaScript regular expressions (<= 200 chars; no backreferences or nested quantifiers -> INVALID_PATTERN); a finding whose value matches any of them is not flagged. Example: [\"^192\\.0\\.2\\.\",\"@example\\.(com|org)$\"]",
      +  "items": {
      +    "maxLength": 200,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 50,
      +  "type": "array"
      +}
    • addedInput schema / properties / contextScoring
      Added value: +{
      +  "default": true,
      +  "description": "Optional boolean, default true. true uses the words just before a match: labels like \"SSN:\", \"phone:\", \"call me\" raise confidence; \"version\"/\"v\" before an IPv4 or phone-shaped number and \"invoice\"/\"order\"/\"ticket\"/\"zip\" before a phone-shaped number drop it (meta.documents[].context_suppressed counts them). false = format-only scoring.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / customDetectors
      Added value: +{
      +  "description": "Optional, default []. 0-20 of your own detectors (regex pattern and/or terms dictionary) for account IDs, ticket formats or member numbers; findings use your type name with category \"custom\" and are redacted and restored like built-in types.",
      +  "items": {
      +    "properties": {
      +      "caseSensitive": {
      +        "default": false,
      +        "description": "Optional boolean, default false.",
      +        "type": "boolean"
      +      },
      +      "confidence": {
      +        "default": "high",
      +        "description": "Optional, default \"high\".",
      +        "enum": [
      +          "high",
      +          "medium",
      +          "low"
      +        ],
      +        "type": "string"
      +      },
      +      "pattern": {
      +        "description": "Optional JavaScript regular expression (<= 200 chars; no backreferences or nested quantifiers). Example: \"\\bMBR-\\d{8}\\b\"",
      +        "maxLength": 200,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "terms": {
      +        "description": "Optional dictionary: 0-500 literal terms matched as whole words. Example: [\"Project Bluebird\"]",
      +        "items": {
      +          "maxLength": 100,
      +          "minLength": 1,
      +          "type": "string"
      +        },
      +        "maxItems": 500,
      +        "type": "array"
      +      },
      +      "type": {
      +        "description": "Type name for this detector, 2-40 chars, letters/digits/_ (uppercased in output). Example: \"MEMBER_ID\"",
      +        "pattern": "^[A-Za-z][A-Za-z0-9_]{1,39}$",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "type"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 20,
      +  "type": "array"
      +}
    • addedInput schema / properties / hashKey
      Added value: +{
      +  "description": "Optional, hash style only. Your own 16-256 char key for deterministic HMAC-SHA256 hashes, so the same value hashes the same in every call. This Worker uses it for this call only and never returns it.",
      +  "maxLength": 256,
      +  "minLength": 16,
      +  "type": "string"
      +}
    • changedInput schema / properties / limit / default
      Previous value: -10New value: +50
    • changedInput schema / properties / limit / description
      Previous value: -"Optional page size: items to return, integer 1-50 (default 10). Example: 10"New value: +"Optional page size: items to return, integer 1-50 (default 50). Example: 50"
    • addedInput schema / properties / priorSealedMap
      Added value: +{
      +  "description": "Optional. meta.sealed_map from an earlier pii_redact_text call (placeholder style only). Keeps the same placeholder for values seen before. Example: \"fqs1.…\"",
      +  "maxLength": 4000000,
      +  "minLength": 10,
      +  "type": "string"
      +}
    • changedInput schema / properties / redactionStyle / description
      Previous value: -"Optional, one of \"placeholder\" | \"mask\" | \"hash\", default \"placeholder\". \"placeholder\" = [EMAIL_1] (reversible); \"mask\" = j***@a***.com, **** **** **** 1111; \"hash\" = [EMAIL:3f2a9c0d1b7e] (salted sha256 prefix, random per-call salt). Example: \"mask\""New value: +"Optional, one of \"placeholder\" | \"mask\" | \"hash\", default \"placeholder\". \"placeholder\" = [EMAIL_k7q2m9xp4a] (reversible with meta.sealed_map); \"mask\" = j***@a***.com, **** **** **** 1111; \"hash\" = [EMAIL:3f2a9c0d1b7e] (salted sha256 prefix; with hashKey an HMAC that stays the same across calls). Example: \"mask\""
    • changedInput schema / properties / returnPlaceholderMap / description
      Previous value: -"Optional boolean, default false. true (placeholder style only) adds meta.placeholder_map {\"[EMAIL_1]\":\"jane@acme.com\"} containing the ORIGINAL sensitive values. Example: true"New value: +"Optional boolean, default false. Deprecated: true (placeholder style only) also adds meta.placeholder_map {\"[EMAIL_…]\":\"jane@acme.com\"} with the ORIGINAL values in clear text. Prefer meta.sealed_map."
    • addedInput schema / properties / sealTtlHours
      Added value: +{
      +  "default": 24,
      +  "description": "Optional integer 1-720, default 24. Hours until meta.sealed_map stops opening.",
      +  "maximum": 720,
      +  "minimum": 1,
      +  "type": "integer"
      +}
  8. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes well past the annotations: discloses that execution happens on the hosted Worker and inputs leave the client, that no inputs/token are stored, that no further network call occurs, and that placeholder ids and hash salts are random per call unless priorSealedMap/hashKey are supplied. It also enumerates error codes, the sealed_map binding to the restore-key header, restore caps and expiry — exactly the context a caller needs for a privacy tool. The nondeterminism note actually corrects a naive reading of idempotentHint=true rather than contradicting it, since the tool has no side effects.

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?

The WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE scaffolding is front-loaded and skimmable, and the length is partly earned by a 31-parameter tool. However the RETURNS section re-lists output fields even though a full output schema exists, and PARAMETERS largely restates schema descriptions, so a meaningful share of the text does not earn its place.

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?

For a 31-parameter privacy tool the definition is unusually complete: it covers the deployment model, reversibility path, restore-key/tenant binding, cost and error taxonomy. It stops short of a 5 because several parameters with real behavioral weight (destinationPolicy presets, returnReceipt, leakCheck, chunkSafe, restoreAudience) appear only in the schema, not the prose.

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 already 100%, so the baseline is 3, but the PARAMETERS block adds real semantics the schema cannot: the same value keeps the same placeholder across all documents in a call, case/format variants collapse, placeholder-shaped input is itself escaped, and priorSealedMap is the mechanism for cross-turn consistency. Some entries (entityTypes, allowList, contextMode) just point at pii_scan_text, and a dozen parameters (tenantId, chunkSafe, leakCheck, returnReceipt, destinationPolicy, etc.) get no treatment in the description at all.

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?

"Return sanitized copies of texts with every local PII/secret finding replaced" names a specific verb, resource and effect, and the WHAT/WHEN/WHEN NOT block explicitly separates it from pii_scan_text (report only) and pii_guard_documents (NER, PDFs, paid). An agent can route correctly without opening the 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?

Explicit WHEN ("right before sending user data to an LLM/third party"), explicit WHEN NOT with the exact alternatives and their differentiators, plus a note that plain http(s) URLs you already hold are handled here free. No alternative is left to inference.

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