Skip to main content
Glama

Fairquery Agent Trust & Data Safety

Fortress Shield: deep PII/secret guard for documents and URLs (paid)

pii_guard_documents
Read-onlyIdempotent

WHAT: Runs the Fairquery Apify Actor llm-data-guard-pii-secrets: everything pii_scan_text does PLUS person-name/location NER, street addresses, public document URLs (txt/md/json/csv/HTML/PDF text layer, <= 10 MB) and restore mode (put originals back into LLM output using a placeholder map). WHEN: Only when you need NER names/addresses, files at URLs/PDFs, or the hosted pipeline. WHEN NOT: Plain text scans (pii_scan_text / pii_redact_text, free), restoring placeholders in an LLM answer (pii_restore_text, free, same result as restore mode), images (no OCR), email deliverability. COST: Paid, billed to YOUR Apify account via your APIFY_TOKEN: $1.50 per 1,000 documents + $0.20 per 1,000 findings. Example: 10 docs with 20 findings ~ $0.02. RETURNS: Paged "document" rows (findings masked; output_text in redact/restore modes; with returnPlaceholderMap the map comes back as an encrypted sealed_map string when this deployment has a seal key) or "error" rows. Tool errors: APIFY_TOKEN_MISSING, APIFY_TOKEN_INVALID, APIFY_PAYMENT_REQUIRED, APIFY_ACTOR_RUN_FAILED, APIFY_TIMEOUT, INPUT_EMPTY. BEHAVIOR: Called from this Fairquery-hosted Worker, which forwards your input and Apify token to Apify and waits 20 s (APIFY_TIMEOUT if the run has not finished). This Worker's code is designed not to store them. The Actor runs in your Apify account and may fetch documentUrls. Up to 1000 texts / 100 URLs (10 MB each). PARAMETERS: texts and/or documentUrls: at least one non-empty (the schema marks both optional; neither -> INPUT_EMPTY, not billed); both may be combined and each text or URL becomes one billed document row. mode="restore" ignores all detector flags; with sealedMap it follows the same restore key rule as pii_restore_text (refusal -> RESTORE_KEY_REQUIRED, nothing billed); a clear-text placeholderMap alone is refused on deployments with a seal key (SEALED_MAP_REQUIRED, nothing billed); a placeholder missing from placeholderMap stays as is. Cost scales with documents and findings, so narrow entityTypes to cut finding charges. limit/offset only page the returned rows: every call processes and bills the whole input again (also when only offset changes), so pick a limit (max 1000) that covers all rows instead of paging. EXAMPLE: {"documentUrls":["https://example.com/report.pdf"],"mode":"redact","detectNames":true}

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "pii_guard_documents"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNoOptional, one of "detect" | "redact" | "restore", default "redact". "detect" = findings only; "redact" = findings + output_text; "restore" = replace placeholders in texts with originals from placeholderMap. Example: "detect"redact
limitNoOptional page size: items to return, integer 1-1000 (default 100). Example: 50
textsNoOptional if documentUrls is given (at least one of the two is required). 0-1000 documents as plain strings, each <= 1,000,000 chars; one billed document row each. 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
allowListNoOptional, default []. 0-1000 exact values never flagged (whole value, case-insensitive). Example: ["support@yourco.com"]
sealedMapNoOptional; used only with mode="restore". A sealed_map from this Worker (pii_redact_text or this tool); it is opened here and sent to the Actor as placeholderMap. Example: "fqs1.…"
detectNamesNoOptional boolean, default false. true enables English person-name NER (type PERSON; lower precision, slower)
entityTypesNoOptional, default omitted = all enabled detectors. 0-40 type names from pii_list_detectors (case-insensitive), e.g. ["EMAIL","PERSON"]; PERSON/LOCATION/STREET_ADDRESS also need detectNames/detectAddresses
entropyScanNoOptional boolean, default false. true also flags unlabeled random-looking tokens (20+ chars) as HIGH_ENTROPY_STRING
documentUrlsNoOptional if texts is given. 0-100 public http(s) URLs (<= 2000 chars) of txt/md/json/csv/HTML/PDF files (<= 10 MB each, PDF text layer only), fetched by the Actor in Apify cloud. Example: ["https://example.com/a.pdf"]
surrogateSeedNoOptional, 1-200 chars. WARNING: visible to the model. Prefer the X-FQ-PII-Surrogate-Seed header, which wins and is not echoed. Omit both for a per-call seed. There is no per-tenant isolation.
placeholderMapNoOptional; used only with mode="restore". Object mapping placeholder -> original value, as returned by an earlier redact call. Example: {"[EMAIL_1]":"jane@acme.com"}
redactionStyleNoOptional, one of "placeholder" | "mask" | "hash" | "label" | "surrogate", default "placeholder"; used in mode="redact" only. Same five styles as pii_redact_text (t2048u #20). placeholder = [EMAIL_1] (reversible), mask = j***@a***.com, hash = [EMAIL:3f2a9c0d1b7e]placeholder
detectAddressesNoOptional boolean, default false. true enables street-address patterns (STREET_ADDRESS) and place-name NER (LOCATION)
returnPlaceholderMapNoOptional boolean, default false. true adds the placeholder map to each row, as an encrypted sealed_map string when this deployment has a seal key (clear-text placeholder_map otherwise); only with mode="redact" and redactionStyle="placeholder"

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\" on the Worker-local guard. Same text and seed always match. Surrogates cannot be restored."New value: +"Optional, 1-200 chars. WARNING: visible to the model. Prefer the X-FQ-PII-Surrogate-Seed header, which wins and is not echoed. Omit both for a per-call seed. There is no per-tenant isolation."
  2. Changed1 schema field changed
    • addedInput schema / properties / surrogateSeed
      Added value: +{
      +  "description": "Optional, 1-200 chars. Only used when redactionStyle is \"surrogate\" on the Worker-local guard. Same text and seed always match. Surrogates cannot be restored.",
      +  "maxLength": 200,
      +  "minLength": 1,
      +  "type": "string"
      +}
  3. Changed2 schema fields changed
    • changedInput schema / properties / redactionStyle / description
      Previous value: -"Optional, one of \"placeholder\" | \"mask\" | \"hash\", default \"placeholder\"; used in mode=\"redact\" only. placeholder = [EMAIL_1] (reversible), mask = j***@a***.com, hash = [EMAIL:3f2a9c0d1b7e]"New value: +"Optional, one of \"placeholder\" | \"mask\" | \"hash\" | \"label\" | \"surrogate\", default \"placeholder\"; used in mode=\"redact\" only. Same five styles as pii_redact_text (t2048u #20). placeholder = [EMAIL_1] (reversible), mask = j***@a***.com, hash = [EMAIL:3f2a9c0d1b7e]"
    • changedInput schema / properties / redactionStyle / enum
      Previous value: -[
      -  "placeholder",
      -  "mask",
      -  "hash"
      -]New value: +[
      +  "placeholder",
      +  "mask",
      +  "hash",
      +  "label",
      +  "surrogate"
      +]
  4. Changed2 schema fields changed
    • changedInput schema / properties / returnPlaceholderMap / description
      Previous value: -"Optional boolean, default false. true adds placeholder_map (ORIGINAL values) to each row; only with mode=\"redact\" and redactionStyle=\"placeholder\""New value: +"Optional boolean, default false. true adds the placeholder map to each row, as an encrypted sealed_map string when this deployment has a seal key (clear-text placeholder_map otherwise); only with mode=\"redact\" and redactionStyle=\"placeholder\""
    • addedInput schema / properties / sealedMap
      Added value: +{
      +  "description": "Optional; used only with mode=\"restore\". A sealed_map from this Worker (pii_redact_text or this tool); it is opened here and sent to the Actor as placeholderMap. Example: \"fqs1.…\"",
      +  "maxLength": 4000000,
      +  "minLength": 10,
      +  "type": "string"
      +}
  5. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only say readOnly/openWorld/idempotent/non-destructive; the description goes far beyond by disclosing paid billing rates with a worked cost example, the 20 s wait and APIFY_TIMEOUT, token handling (APIFY_TOKEN_MISSING/INVALID/PAYMENT_REQUIRED), that the Actor fetches documentUrls from the caller's Apify account, and the non-obvious billing trap that limit/offset only page rows while every call reprocesses and rebills the full input. Idempotency is implicitly qualified by that rebilling note rather than contradicted, since results repeat even when cost does.

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?

The ALL-CAPS heading structure (WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE) is front-loaded and scannable, and the routing constraint appears before the cost detail. It is nonetheless very dense for a single field, and some clauses (duplicating the seal-key rule across the sealedMap and placeholderMap discussions) could be tightened without losing meaning.

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 a 15-parameter, nested-object, paid, open-world tool this covers the axes that matter: cost model, hard limits (1000 texts / 100 URLs, 10 MB, 1,000,000 chars), timeout and failure modes, return row shape and the sealed_map variant, plus a concrete request example. The presence of an output schema means it needn't document full row fields, and it doesn't over-reach.

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

Parameters5/5

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

Schema coverage is 100%, so the baseline would be 3, but the PARAMETERS block adds semantics the schema cannot express: texts and documentUrls are both schema-optional yet at least one is required (INPUT_EMPTY, unbilled), each text or URL bills as one document row, mode="restore" silently ignores detector flags, sealedMap vs clear-text placeholderMap refusals (SEALED_MAP_REQUIRED, RESTORE_KEY_REQUIRED, nothing billed), and narrowing entityTypes to cut finding charges. The limit/offset explanation directly warns against naive pagination.

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?

The WHAT block names the exact upstream pipeline ('Fairquery Apify Actor llm-data-guard-pii-secrets') and states the specific capability delta over the free sibling: person-name/location NER, street addresses, URL/PDF documents, and restore mode. An agent can distinguish this from pii_scan_text without opening either 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 and WHEN NOT sections name the alternatives and the exact condition that selects them: NER names/addresses, files at URLs/PDFs, or the hosted pipeline here; plain text scans to pii_scan_text/pii_redact_text, LLM-answer restoring to pii_restore_text. It also rules out images (no OCR) and email deliverability, which prevents misrouting to email_* siblings.

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