Tool Output PII Detection and Masking Prompt

This prompt is designed for privacy engineers and platform developers who need to sanitize tool outputs before they re-enter an agent's context window. The core job-to-be-done is preventing personally identifiable information (PII) from leaking out of a tool's response and into the agent's reasoning, memory, or subsequent tool calls. This is a critical data hygiene control point in agent architectures where a tool might return raw database rows, unstructured API payloads, or unfiltered log data that contains customer emails, phone numbers, or financial identifiers.

Use this prompt when you have a dedicated sanitization step in your agent's tool-call pipeline—after a tool returns a response but before that response is appended to the agent's message history. It is appropriate for synchronous, string-based tool outputs where you need structured detection results (PII type, confidence score, redaction decision) and a masked version of the original text. The prompt expects a raw tool output string as its primary input and returns a JSON object with masked_output, detected_pii array, and redaction_summary. This is not a real-time streaming solution; it works best on complete, discrete tool responses under a defined token budget.

Do not use this prompt as a replacement for deterministic, rule-based PII scrubbing on structured fields you already control. If you own the tool's output schema and know that field user.email is always an email address, apply a regex or hashing function in application code instead of relying on a model's probabilistic detection. This prompt is also not a substitute for data minimization at the source—if a tool is returning full credit card numbers when only the last four digits are needed, fix the tool or its query before adding a masking layer. Finally, avoid using this prompt for real-time, high-throughput streams where latency and cost per token would make model-based detection impractical; prefer a streaming regex engine with a fallback to this prompt for ambiguous or novel PII patterns.

This prompt template is designed to be inserted between a tool's raw output and the agent's context window. It instructs the model to scan the provided text for personally identifiable information (PII), classify each detected instance by type and confidence, and produce a sanitized version with PII replaced by typed placeholders. The template uses square-bracket placeholders so you can wire it into your application's prompt assembly pipeline without manual editing.

textCopy
You are a privacy-preserving sanitization layer operating between an external tool and an AI agent. Your job is to detect and mask personally identifiable information (PII) in the tool output below before it enters the agent's context.

[CONSTRAINTS]
- Never output unmasked PII under any circumstances.
- Do not alter non-PII content, structure, or formatting.
- If you are uncertain whether a value is PII, flag it with confidence "low" but still mask it.
- Do not add commentary, explanations, or apologies. Return only the JSON object specified in [OUTPUT_SCHEMA].
- If no PII is detected, return an empty detections array and the original text unchanged.

[PII_CATEGORIES]
Detect and classify the following PII types:
- person_name: Full names, first names, last names
- email_address: Email addresses
- phone_number: Phone numbers in any format
- physical_address: Street addresses, postal codes, city/state combinations
- government_id: SSN, passport numbers, driver's license numbers, national IDs
- financial_account: Credit card numbers, bank account numbers, IBANs
- ip_address: IPv4 and IPv6 addresses
- date_of_birth: Explicit birth dates
- medical_record: Patient IDs, medical record numbers
- credential: Passwords, API keys, tokens, secrets

[OUTPUT_SCHEMA]
Return a single JSON object with this exact structure:
{
  "original_length": <integer>,
  "sanitized_text": "<text with PII replaced by typed placeholders>",
  "detections": [
    {
      "type": "<PII category from list above>",
      "original_value": "<detected PII value>",
      "placeholder": "<replacement used in sanitized_text>",
      "confidence": "<high|medium|low>",
      "char_offset_start": <integer>,
      "char_offset_end": <integer>
    }
  ],
  "redaction_summary": {
    "total_detections": <integer>,
    "by_type": {
      "<pii_type>": <count>
    },
    "high_confidence_count": <integer>,
    "medium_confidence_count": <integer>,
    "low_confidence_count": <integer>
  }
}

[PLACEHOLDER_FORMAT]
Use the format [REDACTED_<PII_TYPE>_<INDEX>] for all masked values. For example:
- [REDACTED_EMAIL_ADDRESS_1]
- [REDACTED_PHONE_NUMBER_2]
- [REDACTED_PERSON_NAME_3]

[EXAMPLES]
Input: "Contact John Smith at john.smith@example.com or call 555-123-4567."
Output:
{
  "original_length": 65,
  "sanitized_text": "Contact [REDACTED_PERSON_NAME_1] at [REDACTED_EMAIL_ADDRESS_1] or call [REDACTED_PHONE_NUMBER_1].",
  "detections": [
    {
      "type": "person_name",
      "original_value": "John Smith",
      "placeholder": "[REDACTED_PERSON_NAME_1]",
      "confidence": "high",
      "char_offset_start": 8,
      "char_offset_end": 18
    },
    {
      "type": "email_address",
      "original_value": "john.smith@example.com",
      "placeholder": "[REDACTED_EMAIL_ADDRESS_1]",
      "confidence": "high",
      "char_offset_start": 22,
      "char_offset_end": 44
    },
    {
      "type": "phone_number",
      "original_value": "555-123-4567",
      "placeholder": "[REDACTED_PHONE_NUMBER_1]",
      "confidence": "high",
      "char_offset_start": 54,
      "char_offset_end": 65
    }
  ],
  "redaction_summary": {
    "total_detections": 3,
    "by_type": {
      "person_name": 1,
      "email_address": 1,
      "phone_number": 1
    },
    "high_confidence_count": 3,
    "medium_confidence_count": 0,
    "low_confidence_count": 0
  }
}

[RISK_LEVEL]
[HIGH] - This prompt handles sensitive PII data. The output JSON contains original PII values in the detections array. Ensure this output is handled in a secure environment and never logged or stored without additional redaction of the detections.original_value field.

[INPUT]
Tool output to sanitize:
"""
[TOOL_OUTPUT]
"""

To adapt this template, replace [TOOL_OUTPUT] with the raw text from your tool call. Adjust [PII_CATEGORIES] to match your organization's data classification policy—add or remove types based on your regulatory requirements. If your application cannot safely handle the original_value field in detections, modify [OUTPUT_SCHEMA] to remove it and rely solely on character offsets for audit trails. For high-throughput production systems, consider adding a [MAX_LENGTH] constraint to prevent context window overflow from large tool responses, and pair this prompt with the Tool Output Context Window Budget Check Prompt for defense in depth.

Before deploying this prompt, validate it against your PII detection eval suite. Test with known PII datasets to measure recall and precision per category, and check over-redaction rates on non-PII text. Pay special attention to edge cases: PII in nested JSON structures, PII split across line breaks, non-Latin scripts, and values that resemble PII but are not (e.g., fake phone numbers in documentation). If your risk tolerance requires human review, route low-confidence detections or detections in the government_id and medical_record categories to a review queue before the sanitized output reaches the agent.

The PII detection and masking prompt operates as a synchronous pre-processing gate between a tool's raw output and the agent's context window. Every tool response that might contain user data, API payloads, or unstructured text must pass through this prompt before the agent can reason over it. The harness should treat the prompt as a deterministic filter: same input produces the same masking decisions, which makes caching and regression testing straightforward. Wire it as a middleware function in your agent framework—after the tool executor returns but before the response is appended to the message list. For high-throughput pipelines, batch multiple tool outputs into a single prompt call with clear delimiters to reduce latency overhead.

Validation and retry logic is critical because a malformed JSON response from the PII prompt can corrupt downstream agent state. Implement a strict schema validator that checks for the required fields: masked_output, detections (array of objects with type, confidence, start, end, action), and redaction_summary. If validation fails, retry once with the error message injected into the prompt as [PREVIOUS_ERROR]. If the second attempt also fails, log the raw tool output and the failed prompt responses, then fall back to a conservative redaction strategy—strip all potential PII fields using regex patterns for emails, phone numbers, and credit card numbers—and flag the interaction for human review. Never let unvalidated output enter the agent's context.

Model selection matters for both accuracy and cost. Use a fast, cheaper model (GPT-4o-mini, Claude Haiku, or a fine-tuned small model) for the detection pass because the task is classification-heavy rather than generation-heavy. Reserve larger models only when the confidence scores from the primary model fall below your threshold (e.g., <0.85) or when the output contains complex nested structures like legal documents or medical records. Logging and audit trails should capture: the original tool output hash, the masked output, detection counts by PII type, confidence distributions, the model used, latency, and any validation failures. This audit log serves both debugging and compliance needs—you can prove what data was seen, what was masked, and when the system made errors.

Human review integration is mandatory for high-risk domains. When the prompt detects high-severity PII types (government IDs, financial account numbers, health records) or when confidence scores are below your threshold, route the interaction to a review queue rather than silently masking. The review interface should show the original text with detected spans highlighted, the proposed masked version, and allow one-click approval or correction. Track review decisions to build a feedback dataset for fine-tuning or prompt improvement. Avoid over-redaction by monitoring the false-positive rate—if your system is masking names that are actually product codes or masking dates that are not birthdates, your eval harness should catch this drift before users notice broken agent behavior.

Testing before deployment requires a labeled dataset of tool outputs containing known PII at known positions. Run the prompt against this dataset and measure: recall (did we catch all PII?), precision (did we mask non-PII?), and over-redaction rate (what percentage of masked spans were false positives?). Automate this as a pre-commit or CI check so that prompt changes don't silently degrade detection quality. For streaming tool outputs, buffer the response until complete before running detection—partial outputs can split PII spans across chunks, causing missed detections. If latency is critical, implement a sliding window approach that processes chunks as they arrive but holds back the last N tokens until the next chunk confirms no split entities.