> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ToolGuard Models
> Industry-leading AI security suite for MCP ecosystems
## Industry-Leading AI Security for MCP Ecosystems
Runlayer ToolGuard is an industry-leading suite of specialized machine learning models that protect your MCP environment from tool poisoning, prompt injection, and output manipulation attacks. With fast 50-100ms inference times, ToolGuard delivers real-time threat detection without compromising performance.
Currently featuring three specialized threat classification models, with additional models in active development to address emerging attack vectors.
## The Models
### Tool List Guard
Scans tool definitions at registration to detect risky descriptions, prompt injection attempts, and hidden instructions before tools are made available to your environment.
### Tool Call Guard
Scans tool execution outputs in real-time to detect risky responses, data exfiltration attempts, and prompt injection before they reach your LLMs.
### Tool Intent Guard
Detects tool intent drift from prompt injections that lead to data exfiltration, privilege escalation, credential theft, and infrastructure damage. Unlike the Tool Call Guard which evaluates individual responses, Tool Intent Guard analyzes tool inputs and outputs together to detect semantic misalignment — catching cases where a tool's actual behavior diverges from what was requested.
### Skill File Scanning
ToolGuard can also scan **skill files** uploaded to the platform. Each file's content is analyzed using the same threat classification models, with results cached per content hash and scanner version. Large files are automatically chunked for processing.
Skill file scanning runs when skills are uploaded via the CLI (`skills push`), imported from a GitHub URL, or created/updated via the API, producing per-file risk scores and an overall skill-level classification.
#### Skill Risk Policy
Admins can configure how the platform responds when a skill scan detects elevated risk. Navigate to **Settings → Security Scanners** to set the action for each risk tier:
| Risk tier | Default action | Options |
| ---------- | -------------- | ------------------- |
| **High** | Block | Block, Alert, Allow |
| **Medium** | Alert | Block, Alert, Allow |
* **Block** — the skill import is rejected
* **Alert** — the skill is imported with a warning badge visible in the UI; acceptance is logged to the Audit Log
* **Allow** — the skill is imported without restriction
Low and Minimal risk skills are always allowed. These settings apply globally to all skill imports (CLI, API, web UI, and web import from GitHub).
### LLM Risk Categorization
When Tool List Guard flags a tool at **Medium** or **High** risk, an LLM-based categorizer automatically classifies the threat into specific attack categories. The full taxonomy includes:
* Prompt Injection
* Data Exfiltration
* Privilege Escalation
* Destructive Action
* Unauthorized Communication
* Resource Abuse
* Shadow Persistence
* Context Poisoning
* Guardrail Bypass
* Supply Chain Compromise
Categories are not mutually exclusive — a single tool can match multiple categories. These labels appear in security violation details and audit logs, replacing generic "risky tool" messages with actionable context so you know *what kind* of threat was detected.
LLM categorization requires the Bedrock integration to be enabled in your deployment. When disabled, violations retain the default ToolGuard reason.
### What a Finding Shows
Findings explain the reasoning behind a risk assessment, not just a score. Each Tool List Guard finding includes:
* **Confidence score and risk tier** — the model's 0.0–1.0 score, mapped to a tier (see [Risk Tiers](#risk-tiers))
* **Threat categories** — the attack categories assigned by LLM Risk Categorization (above)
* **Areas of concern** — when a tool scores above the risk threshold, ToolGuard runs an additional analysis pass that narrows down the specific excerpt of the tool definition that triggered the detection. This excerpt is stored with the finding and displayed under **Area of concern** on the connector detail page, alongside the tool's name and full description — so reviewers see exactly which text caused the flag.
Tool Call Guard works the same way for blocked outputs: the finding includes the specific portion of the tool output that triggered the block, not just the score.
Additional specialized models are in development to address new attack vectors as they emerge in the MCP ecosystem.
## Why Industry-Leading?
**Purpose-Built for MCP** - Custom-trained threat classification models specifically designed for MCP ecosystem attacks.
**High Performance** - Fast inference with typical scan times of 50-100ms.
**Continuously Evolving** - Models are regularly refined based on emerging threat patterns.
**Battle-Tested** - Deployed in production environments protecting real-world MCP deployments.
**Enterprise-Ready** - Complete audit logging, flexible configuration, and Security Dashboard integration.
## Configuration
Navigate to **Settings → Security Scanners** to enable Runlayer ToolGuard models.
### Scanner coverage
Different scanners run at different points in the agent flow:
| Surface | Scanner coverage |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Tool definitions** | Tool List Guard scans names, descriptions, and schemas when a connector is registered or re-scanned. |
| **Tool inputs** | PII, credential, invisible-character, and Tool Intent Guard checks can inspect tool arguments before execution. |
| **Tool outputs** | Tool Call Guard, PII, credential, invisible-character, and Tool Intent Guard checks can inspect results before they reach the model. |
| **Skill files** | Skill file scanning runs on uploaded skill content before import. |
| **Session trajectory** | [AgentGuard](/agentguard) evaluates multi-turn behavior across prompts, reasoning, tool output, and follow-up reasoning. |
User prompts and model responses appear in [Sessions](/platform-sessions) when full session scanning is enabled. Per-call ToolGuard scanners focus on MCP and local tool traffic; AgentGuard is the session-level scanner for behavior drift across the conversation.
### Sensitivity Levels
Each scanner phase (Tool List Guard, Tool Call Guard, Tool Intent Guard) has a configurable **sensitivity** that controls how aggressively it flags findings:
| Level | Behavior |
| ---------------------- | ------------------------------------------------------------ |
| **Strict** | Lowest tolerance — flags more items, fewer false negatives |
| **Balanced** (default) | Recommended for most environments |
| **Moderate** | Highest tolerance — fewer flags, useful for noisy connectors |
Sensitivity is set globally in **Settings → Security Scanners** and can be overridden per connector in the connector's security settings, or per client (browser, CLI, IDE) in the **Per-client overrides** section. Connectors without an explicit override inherit the global value.
Scanner tuning is global, per-connector, or per-client. Public docs do not document
per-user, per-group, or per-agent scanner thresholds. For self-hosted
deployments, Tool List Guard risk-tier thresholds can also be tuned with the
environment variables listed under [Risk Tiers](#risk-tiers).
### Violation Actions
Each scanner has a configurable **action** that controls what happens when it detects a finding. The available actions depend on the scanner type:
| Action | Behavior |
| ------------------------ | --------------------------------------------------------------------------------------------- |
| **Block** | Reject the request — the tool call does not proceed |
| **Block (Self-Approve)** | Block the request but allow the caller to approve and retry (per-connector only, PII scanner) |
| **Mask** | Redact or strip the detected content, then let the request continue |
| **Alert** | Log the detection but take no blocking action — the request proceeds unchanged |
| **Allow** | Disable the scanner entirely |
Not every scanner supports every action. The table below shows which actions are available for each scanner:
| Scanner | Allow | Alert | Mask | Block |
| ------------------------------------------------------------------------------- | ----- | -------------------- | ------------------------ | ----- |
| **PII detection** | Yes | Yes | Yes (redact PII values) | Yes |
| **Invisible character detection** | Yes | Yes | Yes (strip hidden chars) | Yes |
| **Credential detection** | Yes | Yes | Yes (mask credentials) | Yes |
| **ToolGuard ML scanners** (Tool List Guard, Tool Call Guard, Tool Intent Guard) | Yes | Yes | — | Yes |
| **Skill risk policy** | Yes | Yes (warn on import) | — | Yes |
**Defaults**: PII detection defaults to **Alert**. Invisible character detection and credential detection default to **Mask**. ToolGuard ML scanners default to **Block**.
Actions are set globally in **Settings → Security Scanners** and can be overridden per connector or per client.
### Custom Security Messaging
When a scanner blocks a call, Runlayer returns an explanation to the calling agent (and the user). By default this ends with generic guidance to contact your Runlayer administrator. Admins can replace that guidance with their own — for example, pointing users to a specific Slack channel or internal runbook instead of an inbox.
Navigate to **Settings → Security Scanners → Edit Security Messaging**. Each message has a fixed prefix that is always shown (the violation details and audit-log link); your custom text replaces only the closing **What to do** guidance. A live preview shows exactly what agents will receive.
The following messages can be customized:
| Message | Shown when |
| ---------------------- | -------------------------------------------------------------------- |
| **Security block** | A security scanner blocks a tool call |
| **Self-approve** | A block can be approved and retried by the caller |
| **Policy denial** | A [policy](/platform-policies) denies a tool call or resource access |
| **Connector disabled** | Tools on a disabled connector are called |
| **No access** | Someone connects to a connector they have no access to |
Messages support a small set of `{{variable}}` placeholders — such as `{{server_name}}`, `{{tool_name}}`, `{{reason}}`, and `{{audit_log_link}}` — that are filled in at runtime. The editor lists the variables available for each message. Leaving a message unset falls back to the built-in default.
### PII Detection
PII scanning uses pattern-based detection with validators to identify sensitive data in MCP traffic. The following built-in PII types are detected:
| Type | Description |
| -------------------- | --------------------------------------------------------- |
| **SSN** | US Social Security numbers |
| **Credit Card** | Card numbers (validated with Luhn check) |
| **Phone** | Phone numbers (with context validation) |
| **Email** | Email addresses |
| **Passport** | Passport numbers (with context validation) |
| **Driver's License** | US driver's license numbers |
| **IBAN** | International Bank Account Numbers |
| **IP Address** | IPv4 addresses |
| **Date of Birth** | Dates of birth (with context validation) |
| **MRN** | Medical Record Numbers |
| **VIN** | Vehicle Identification Numbers (with checksum validation) |
| **Bitcoin** | Bitcoin wallet addresses |
| **Ethereum** | Ethereum wallet addresses |
Admins can also add **custom PII rules** with regex patterns in **Settings → Security Scanners**. Custom rules run alongside built-in patterns and appear in audit logs with a `CUSTOM` label. Individual built-in types can be disabled per organization.
PII masking redacts matched values before the request continues. Public docs do not currently describe stable placeholder substitution that preserves the same replacement token for the same PII value across a session.
### PII Scan Direction
PII detection can be applied to tool **inputs**, **outputs**, or **both**. The direction controls which traffic the PII scanner inspects:
| Direction | Behavior |
| ------------------- | ---------------------------------- |
| **Input** (default) | Scans data sent to MCP tools |
| **Output** | Scans data returned from MCP tools |
| **Both** | Scans in both directions |
Set the direction globally in **Settings → Security Scanners** and override per connector in the connector's security settings, or per client in the **Per-client overrides** section. Connectors without an override inherit the global value.
### Risk Tiers
Tool List Guard assigns a risk tier to each scanned tool based on its confidence score. The default thresholds are:
| Tier | Score Range | Meaning |
| ----------- | ----------- | --------------------------------- |
| **Minimal** | \< 0.6 | Clean scan, no concern |
| **Low** | 0.6 – 0.7 | Low-confidence flag |
| **Medium** | 0.7 – 0.9 | Elevated risk, review recommended |
| **High** | ≥ 0.9 | High-confidence detection |
Self-hosted deployments can tune these thresholds via environment variables:
* `RUNLAYER_TOOL_GUARD_LIST_RISK_THRESHOLD_LOW` (default `0.6`)
* `RUNLAYER_TOOL_GUARD_LIST_RISK_THRESHOLD_MEDIUM` (default `0.7`)
* `RUNLAYER_TOOL_GUARD_LIST_RISK_THRESHOLD_HIGH` (default `0.9`)
If you don't see Runlayer ToolGuard options, you need to configure your Runlayer deployment to enable the GPU ToolGuard infrastructure. See [deployment documentation](/deployment/overview) for setup instructions.
## Submitting Feedback
When a ToolGuard scan result is wrong — a benign tool flagged as risky (**false positive**) or a risky one that slipped through (**false negative**) — you can report it back to Runlayer. Feedback is used to improve future model accuracy.
Submit feedback to the same API surface as the [scoring endpoints](/platform-api), authenticated with an organization API key that has the **Security Scan** role (sent in the `x-runlayer-api-key` header):
```bash theme={null}
curl -X POST "$RUNLAYER_BASE_URL/api/v1/security/feedback" \
-H "x-runlayer-api-key: $RUNLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"endpoint": "tool_call",
"feedback_type": "false_positive",
"human_label": "allow",
"notes": "Internal reporting tool — the output is expected, not exfiltration.",
"scan_context": {
"tool_name": "generate_report",
"score": 0.94,
"decision": "block"
}
}'
```
| Field | Required | Description |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `endpoint` | Yes | Which score endpoint the feedback is about: `tool_list`, `tool_call`, `tool_guard_io`, or `skill` |
| `feedback_type` | Yes | `false_positive` (flagged but safe) or `false_negative` (missed a real risk) |
| `human_label` | Yes | The label you believe is correct. Canonical values are `block` / `allow`, but any short label is accepted |
| `notes` | No | Free-form context explaining the correction |
| `scan_context` | No | The scanned payload plus the score/decision you disagree with, echoed back for triage |
A successful submission returns `201` with a `submission_id`. Feedback is retained per organization for model review.
Feedback submission isn't available in certain self-hosted cloud environments. Where it's unavailable, the endpoint returns `503`.
## Monitoring
**Security Dashboard** - View detection timelines, violation trends, and common threat types
**[Connector Pages](/platform-connectors)** - Tool List Guard warnings appear directly on connector detail pages when potentially risky tools are detected
**[Audit Logs](/platform-audit-logs)** - Full history of detections, blocks, and configuration changes with confidence scores
**[Sessions](/platform-sessions)** - Review scanner outcomes in full AI session timelines
**[AgentGuard](/agentguard)** - Session-level behavior monitoring across the agent trajectory
## Best Practices
* Use **per-server overrides** for high-risk external servers
* Use **per-client overrides** when specific AI clients (e.g., IDE vs. browser) need different scanner behavior
* Combine with [MCP access policies](/platform-policies) for layered security
* Review flagged tools with your security team before blocking
## Staying Ahead
Runlayer ToolGuard models are continuously refined based on emerging threat patterns in the MCP ecosystem. Our commitment to continuous innovation ensures you have industry-leading defenses as new attack techniques emerge. Deployed model versions are tracked in the [ToolGuard Model Versions](/toolguard-model-versions) changelog.
## Model Attribution
The Runlayer ToolGuard suite utilizes [GA Guard Lite](https://huggingface.co/GeneralAnalysis/GA_Guard_Lite) for threat classification embeddings and model inputs. GA Guard Lite is licensed under Apache 2.0.
## Related Resources
MCP security guidelines and recommendations
View detailed activity and security logs
Monitor scanner outcomes in AI session timelines
Session-level behavior monitoring across the agent trajectory
Configure MCP access control policies