Pseudonymise medical and clinical documents before they're processed by AI or
shared. Redacta replaces patient identifiers with labelled tokens —
[PATIENT_NAME_1], [NHS_NUMBER_1], [DATE_OF_BIRTH_1], … — while leaving the
clinical meaning intact, and returns a redaction report alongside the cleaned
text.
It started as an Agent Skill and is now one engine shipped across eight surfaces — an iOS app, agent skill, MCP server, a self-hosted HTTP service with a Kubernetes deployment, two libraries, a CLI, and a FigJam whiteboard plugin.
Running this in production? Redacta offers a small number of fixed-price design-partner integrations for teams shipping AI agents on clinical or patient data — deployment in your environment, one real workflow integrated, and a data-flow document written for your DPO. Details →
Surface | Folder | Get it |
iOS app — iPhone (app, Share Extension, widget) | Build with Xcode — see | |
Agent skill (Claude Code / apps / API) |
|
|
MCP server (Claude Desktop, Cursor, …) |
|
|
TypeScript library |
|
|
Python library |
|
|
Command-line tool |
|
|
Self-hosted HTTP service + Kubernetes |
| |
FigJam plugin |
|
The detection logic lives in one place — the TypeScript engine
(@pharmatools/redacta, in npm-package/), which the MCP server and the
FigJam plugin consume, and which the iOS app runs on-device via JavaScriptCore.
The Python package mirrors it for pip users; the agent skill adds LLM reasoning
for free-text names on top of the deterministic patterns.
Related MCP server: PubCrawl
Two layers:
Patterns (deterministic). A bundled script (scripts/redact_structured.py,
Python standard library only, no network) matches fixed-format identifiers:
NHS numbers (Modulus-11 validated), UK National Insurance numbers, dates of
birth, UK postcodes, phone numbers, emails, and hospital/MRN numbers. US SSN
and ZIP codes are also handled.
Reasoning (judgement). The skill then has the agent handle what patterns can't: patient names (told apart from the clinicians treating them), relatives and carers, postal addresses, and identifying ages.
Self-check. A final pass re-reads the output for any identifier that slipped through before the report is written.
It also works in reverse. Re-identification (scripts/reinstate.py) takes the
token map from an earlier redaction and restores the original values — so you can
redact a document, run it through another AI tool, and put the real details back
locally. Redact → process → re-identify is a complete round trip, and identifiers
only ever exist on your machine.
Safe Harbor mode. Ask for HIPAA Safe Harbor (or "US de-identification") and Redacta applies a stricter pass: all dates (not just the date of birth), all specific ages, and the remaining HIPAA identifiers — fax, certificate/licence, device serial, VIN, and health-plan beneficiary numbers.
Organisations that can't let identifiable text leave their environment can
run Redacta inside their own infrastructure: a small HTTP service
(gateway-service/) deployable into an existing
Kubernetes cluster with plain YAML — two stateless replicas behind a
Service for redact/reinstate, an optional single-replica session boundary
for the protect → release loop, health probes, resource limits, restrictive
security defaults, and no-PHI logging. Text is pseudonymised before it
reaches any external AI service, and the processing boundary stays under
your control. Walkthrough (local kind cluster included):
gateway-service/k8s/README.md ·
concepts: docs/KUBERNETES.md.
Deploying somewhere a DPO will ask questions? There's a one-page security &
data-protection summary at
pharmatools.ai/redacta-security.
Claude Code
git clone https://github.com/nickjlamb/redacta ~/.claude/skills/redactaThen invoke it with /redacta, or let it trigger automatically when you ask to
redact or de-identify clinical text.
Claude apps / API
Zip the repository folder and upload it as a skill.
Path | What it is |
| The skill — instructions plus metadata |
| Pattern specs, the Modulus-11 algorithm, NI prefix rules, the date-of-birth vs clinical-date rule, token vocabulary, limitations |
| The deterministic pattern layer |
| The re-identification layer (restore originals from a token map) |
| Tests for the pattern layer |
| Tests for the re-identification layer |
| Example evaluation scenarios |
Run the tests:
python3 scripts/test_redact_structured.py
python3 scripts/test_reinstate.pyRedacta is a strong first line of defence, not a guarantee. It won't catch every possible identifier and isn't a substitute for formal data-protection processes. Always review the redaction report before sharing text.
MIT-0 (MIT No Attribution). Built by PharmaTools.AI.
Scan generated text for verbatim reappearance of the original values held in a protected session (tolerant of spacing, dashes and case for identifier-like values) and re-tokenise anything found. Returns which token categories leaked — never the raw values — plus the sanitised text and a general self-check. Scope is verbatim reappearance only: paraphrases and inferred identities are not detected.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Model output to inspect. | |
| session_id | Yes | The session_id returned by protect. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds meaningful behavior beyond the readOnly annotation: tolerant matching for spacing, dashes and case, re-tokenisation of found values, and an explicit guarantee that raw values are never returned. This lets an agent predict both safety and output shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences carry all critical information, with the operation and key guarantee front-loaded. No filler or repetition of schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by specifying the returned elements: leaked token categories (never raw values), sanitised text, and a self-check. It also states matching tolerance and detection scope, so an agent has enough to call and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema describes both parameters fully (text and session_id, with session_id explicitly linked to protect), so baseline 3 applies. The description adds no parameter-specific detail, which is acceptable at 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Scan ... and re-tokenise') with a clear resource (generated text and protected session values). The restriction to 'verbatim reappearance only' distinguishes it from sibling tools like self_check and redact even though no sibling is named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The scope line makes the intended use clear: run this after generation to catch verbatim leaks from a protected session, not paraphrases or inferred identities. It provides a when-not condition ('paraphrases and inferred identities are not detected') but doesn't explicitly name an alternative tool for those cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a session's private mapping immediately instead of waiting for expiry. Idempotent. After this, no restoration is possible for that session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session_id to discard. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint false, openWorldHint false), the description adds crucial behavioral details: immediate deletion rather than waiting for expiry, idempotency, and permanent irreversibility. These are exactly the behavioral traits an agent needs to know before invoking a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Each sentence earns its place: it states the action, the idempotency trait, and the irreversible consequence. There is no filler or repetition, and the most important operational fact ('immediately instead of waiting for expiry') is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description covers the operation, the effect, and the consequence. It does not specify error handling for unknown session IDs or return values, but these are not necessary for basic correct invocation and the description is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single session_id parameter fully described in the schema. The description adds no parameter-level detail beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') with a clear resource ('a session's private mapping') and distinguishes the behavior from the default expiry-based cleanup. It also contrasts with the sibling 'reinstate' by stating that no restoration is possible afterwards, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames when this tool is appropriate: when immediate deletion is desired instead of waiting for expiry. It also implicitly communicates the irreversible nature, acting as a cautionary usage signal, though it does not explicitly name alternative tools or provide a when-not-to-use list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Redact patient identifiers and PII, replacing each distinct value with a labelled token ([NHS_NUMBER_1], [PATIENT_NAME_1], ...). The reversal mapping is kept privately inside the Redacta server and is NEVER included in this response — you receive only the protected text, an opaque session_id for later controlled restoration, a count of what was replaced, and a self-check of possible leftovers. Sessions expire automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The text to protect. | |
| categories | No | Which pattern sets to apply. Defaults to clinical + general. 'clinical' = NHS/NI/DOB/MRN/postcode/SSN/ZIP/email/phone/names; 'general' = URLs, IPs, payment cards, IBANs, account numbers, vehicle regs; 'safeharbor' = strictest, HIPAA Safe Harbor — implies clinical + general and also removes ALL dates (not just DOB), ages, fax, licence, device-serial, VIN and health-plan numbers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses behavior beyond the sparse annotations: the mapping is never returned, the response includes sensitive session_id and self-check, and sessions auto-expire. This is exemplary transparency for a non-read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core mechanism (token replacement) and then lists outputs and constraints. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description fully explains the return values (protected text, session_id, count, self-check) and the session expiration caveat. Nothing an agent needs to call correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented. The tool description does not add extra meaning beyond the schema, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Redact' and the resource 'patient identifiers and PII', and explains the output. It does not explicitly differentiate from sibling tools like 'redact' or 'reinstate', preventing a full 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: the tool is for reversible redaction, providing a session_id for later restoration. However, no explicit comparison to alternatives like 'redact' or 'reinstate' is given, so the agent must infer when to use this vs. siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
LEGACY: like protect, but returns the token_map (token -> original value) in the response, which places the reversal key in the client and potentially the model context. Kept for backward compatibility and client-managed workflows. Prefer protect, which keeps the mapping server-side.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The text to redact. | |
| categories | No | Which pattern sets to apply. Defaults to clinical + general. 'clinical' = NHS/NI/DOB/MRN/postcode/SSN/ZIP/email/phone/names; 'general' = URLs, IPs, payment cards, IBANs, account numbers, vehicle regs; 'safeharbor' = strictest, HIPAA Safe Harbor — implies clinical + general and also removes ALL dates (not just DOB), ages, fax, licence, device-serial, VIN and health-plan numbers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description adds non-obvious risk: the token_map exposes the reversal key in the client and potentially the model context. It also discloses that protect keeps the mapping server-side, a key behavioral difference beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the legacy warning and key differentiator front-loaded. Every sentence adds value and none repeat what the schema already states.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though there is no output schema, the description covers the essential return behavior (token_map), the exposure risk, and the recommended alternative. With full schema coverage and annotations, nothing an agent needs to invoke or avoid this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; both text and categories have descriptive entries in the input schema. The description does not add parameter-level detail beyond mentioning the response token_map, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation (redact/pseudonymise), flags it as legacy, and differentiates it from protect by the token_map return. An agent can tell redact apart from its main sibling 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Prefer protect' and names the only condition for choosing redact: backward compatibility or client-managed workflows. This is a clear when/when-not directive with the alternative identified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
LEGACY: reverse a redaction using a token map held by the client (from the legacy redact tool). Restored personal data will appear in this tool result. For session-based restoration that keeps mappings server-side, use protect + release_to_file.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Text containing Redacta tokens to restore. | |
| token_map | Yes | Token map, e.g. {"[NHS_NUMBER_1]": "943 476 5919"}. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds important behavioral context: restored personal data will appear in the tool result, which is a meaningful privacy warning. The description does not mention edge cases like unmapped tokens, but the read-only annotation covers the safety profile and there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. 'LEGACY:' is front-loaded, immediately signaling the tool's status, and each sentence serves a distinct purpose: explaining what it does and directing to an alternative when appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter legacy transform with a readOnly annotation, the description is nearly complete: it identifies inputs, warns about PII exposure, and names the alternative workflow. A small gap is that it does not explicitly state the return format, though the description's mention of restored personal data appearing in the result covers the main concern.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters fully, so the baseline is 3. The description adds value by clarifying that the token_map is client-held from the legacy redact tool and that the text contains Redacta tokens, which helps the agent understand the provenance and expected format of the inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: reverse a redaction using a client-held token map from the legacy redact tool. It also differentiates this tool from session-based restoration by naming protect and release_to_file as the alternative, so an agent can identify this tool's exact role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: use this tool for legacy client-held token maps, and for session-based restoration that keeps mappings server-side, use protect + release_to_file. This provides both a clear when-to-use and when-not-to-use signal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore original identifiers into text produced from a protected session, writing the result to a file inside the server's configured release directory (REDACTA_RELEASE_DIR). Returns only a receipt — file path, size, and counts — so restored data never enters the model context. This is the privacy-preserving way to complete the round trip.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Text containing Redacta tokens to restore. | |
| session_id | Yes | The session_id returned by protect. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the sparse annotations (readOnlyHint=false, openWorldHint=false) by disclosing the side effect of writing to REDACTA_RELEASE_DIR and the exact return behavior: 'Returns only a receipt — file path, size, and counts.' It also states the privacy property that restored data never enters the model context, which is critical behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action and destination. The third sentence adds usage context but is somewhat redundant with the privacy point already made in the second sentence, keeping it from a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two well-documented parameters and no output schema, the description covers the essential details: what it does, where it writes, what it returns, and why it is privacy-preserving. Nothing an agent needs to invoke it correctly or understand its side effects is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters fully. The description adds no additional meaning beyond what the parameter descriptions provide, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Restore'), a specific resource ('original identifiers'), and a concrete destination ('a file inside the server's configured release directory'). It clearly distinguishes this from siblings like reinstate by emphasizing that the result is written to a file and 'restored data never enters the model context.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool is appropriate: 'the privacy-preserving way to complete the round trip.' It implies that alternatives may return data into context, but it does not explicitly name them or state when not to use this tool, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan already-redacted text for anything that still looks like an identifier (long numbers, emails, postcodes, URLs). A second pair of eyes, not a guarantee. Returns a list of possible leftovers to review.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Redacted text to re-scan. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already signals safety, and the description adds valuable non-obvious context: the tool is deliberately non-authoritative ('not a guarantee') and returns only 'possible leftovers' rather than a definitive result. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no waste. The action and target are front-loaded, the reliability caveat is compact, and the return type is stated clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only tool with no output schema, the description covers input, output shape ('list of possible leftovers'), and reliability expectations. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single 'text' parameter has 100% schema coverage, so the baseline is 3. The description adds extra meaning by clarifying what an identifier can look like, which helps the agent understand what input is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Scan') and exact resource ('already-redacted text'), and defines the target class with concrete examples (long numbers, emails, postcodes, URLs). It does not explicitly contrast with the sibling 'check_output', so it stays at 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The modifier 'already-redacted text' and the phrase 'second pair of eyes' clearly indicate a post-redaction review pass, giving enough context for an agent to choose this tool. It does not enumerate exclusions or name an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.1.0check_outputdiscard_sessionprotectredactreinstaterelease_to_fileself_checkScored across 7 tools
Each tool has a clearly distinct purpose: protect vs redact are differentiated by legacy status and return behavior, release_to_file vs reinstate by client vs server-side mapping, plus check_output, discard_session, and self_check each occupy unique roles. No ambiguity in selection.
All tools use snake_case and a verb-first pattern, though the structure varies (protect, release_to_file, check_output, discard_session, redact, reinstate, self_check). The legacy tools follow the same style but the naming is consistent enough to be predictable.
Seven tools is well-scoped for a redaction/restoration server: core redaction, restoration, leakage checking, session management, and legacy compatibility all have dedicated tools without bloating the surface.
The full lifecycle is covered: redaction (protect), restoration (release_to_file), output verification (check_output), session cleanup (discard_session), and leftover scanning (self_check), plus legacy paths. No obvious gaps for the intended domain.
HealthGuard - 12-tool health/medical AI safety MCP: PII redaction, HIPAA, GDPR Art.9.
Redact PII from text before it reaches a model. Nothing stored, no third-party AI.
Privacy-preserving synthetic health data generation. FHIR R4/R5 compliant.
Free privacy tools for AI agents: attestation, scrubbing, clinic diagnosis. No tracking.
