Tool scanning
Check tool definitions, including MCP server tool lists, for tool poisoning before the model sees them.
scanTools() finds tool poisoning: instructions hidden in a tool's description or parameter schema. The model reads that text on every request and the user usually never sees it, so a malicious or compromised MCP server can use it to steer the agent.
Run it on each MCP server's tool list before you pass the tools to a model, and again whenever the server reports a change:
import { scanTools } from "@zeroleaks/shield";
const { tools } = await mcpClient.listTools();
const scan = scanTools(tools);
if (scan.flagged) {
for (const tool of scan.tools) {
if (tool.result.detected || tool.issues.length > 0) {
console.warn(`Refusing tool ${tool.name}:`, tool.result.matches, tool.issues);
}
}
}
const safeTools = tools.filter(
(_, i) => !(scan.tools[i].result.detected || scan.tools[i].issues.length > 0)
);Parameters
function scanTools(tools: ToolDefinition[], options?: ScanToolsOptions): ScanToolsResult
function scanToolsAsync(tools: ToolDefinition[], options?: ScanToolsOptions): Promise<ScanToolsResult>tools can mix these shapes:
| Shape | Where the schema is read from |
|---|---|
MCP (tools/list result) | inputSchema |
OpenAI Chat Completions { type: "function", function: { ... } } | function.parameters |
| OpenAI Responses API function tool | parameters |
| Anthropic | input_schema |
| AI SDK | parameters or inputSchema |
For each tool, Shield joins the description and the free text in its schema and passes them to detect(). Schema text means descriptions, titles, examples, defaults, enum and const values, and parameter names split into words, at any depth.
options takes every detect() option plus maxDescriptionLength and pins.
Returns
| Field | Type | Description |
|---|---|---|
flagged | boolean | True when any tool was detected or has an issue |
tools | Array<{ name, result, issues }> | Per tool: the detect() result and a list of issues |
| Issue | Meaning |
|---|---|
duplicate_name | Two tools share a name, so one can shadow the other |
hidden_characters_in_name | The name contains invisible or non-ASCII characters, often used to impersonate another tool |
oversized_description | The description is longer than maxDescriptionLength (4,000 characters by default), a common way to bury instructions |
changed_since_pinned | The definition differs from the one pinned in pins (see Pin tool definitions) |
Use hosted detection
scanTools runs synchronous local checks and rejects asynchronous detector options. For a hosted or asynchronous detector, use scanToolsAsync:
import { createHostedDetector, scanToolsAsync } from "@zeroleaks/shield";
const shield = createHostedDetector({
apiKey: process.env.ZEROLEAKS_API_KEY,
model: "shield",
});
const scan = await scanToolsAsync(tools, shield.options());The MCP wrapper awaits checks when configured with a hosted detector.
Pin tool definitions
A server can change a tool after you reviewed it, keeping the name and changing what the model reads (a "rug pull"). pinTools(tools, pins?) returns pins for the tools, and scanTools(tools, { pins }) reports every tool whose definition no longer matches its pin as changed_since_pinned:
import { pinTools, scanTools } from "@zeroleaks/shield";
let pins = pinTools(approvedTools); // plain data: save it with JSON.stringify
// later
const scan = scanTools(currentTools, { pins });
pins = pinTools(currentTools, pins); // pins new tools; changed ones keep their old pinA pin is the canonical JSON of the tool's description, title, input and output schemas, and annotations. Keys are sorted, so reordering a schema doesn't count as a change. pinTools() never overwrites an existing pin: a changed tool stays flagged until you remove its entry. The MCP client wrapper pins tools for you.
False positives
On 7,312 unique benign tool definitions from the Hermes function-calling dataset (NousResearch, Apache-2.0), scanTools() flagged 20 (0.27%), all by the classifier and all with very short descriptions, such as "Create a new user" or "Send an email". Raise classifier.threshold if short descriptions in your tool lists get flagged, or use onFlaggedTools: "warn" in the MCP client while you review them.
Limitations
scanTools() only reads the definitions. The provider wrappers scan tool results (scanToolResults, on by default), or you can call detect() on them.
Output scanning
Find and redact credentials, personal data, exfiltration links, injection payloads, canary tokens, and system prompt leaks in model output.
Tool policy
A deterministic policy for an agent's tool calls, covering declared tools, argument schemas, allow and deny lists, call limits, and data flow.