ToolTrust: reviewing AI tool permissions before connecting agents

An AI agent can have a reasonable task and still be connected to a tool with unreasonable permissions.

A documentation lookup tool should not quietly gain arbitrary shell execution, filesystem-wide access, or unrestricted network delivery. Reviewing those declarations before connecting the tool is a small but useful defensive step.

ToolTrust is a browser-based application for that review. It checks a custom JSON manifest, produces findings with stable rule IDs, and offers a manual review checklist and redacted JSON/Markdown reports.

It is a static review aid. It does not enforce permissions, execute tools, inspect a server's implementation, or certify that an agent is safe.

What the application reviews

The engine contains 15 rules across seven categories:

Category	Review signal
Description override	Tool metadata that asks an agent to ignore instructions or suppress approval
Command execution	Declared shell/process/code execution, particularly without human approval
Overbroad access	Wildcard permissions, root filesystem scope, or missing path restrictions
Unapproved side effects	Mutating actions or external sends without an approval gate
Insecure transport	Remote HTTP, URL credentials, or missing declared authentication
Secret-bearing inputs	Top-level input fields requesting credentials and permissive additional properties
Data egress	Broad destination scope and combined read-and-send capabilities

Every finding includes a severity, the inspected field, bounded evidence, an explanation, remediation guidance, and a checklist. Severity reflects review priority rather than a probability of compromise.

A small example

ToolTrust expects its own review format. It is not a native MCP server configuration parser or a complete JSON Schema validator.

This synthetic tool is restricted to reading an approved documentation directory:

{
  "tools": [
    {
      "name": "lookup_docs",
      "description": "Search approved documentation. Never ignore user approval.",
      "permissions": ["files:read"],
      "approvalRequired": true,
      "allowedPaths": ["/workspace/docs"],
      "transport": {
        "type": "https",
        "endpoint": "https://docs.example/mcp",
        "auth": "token"
      },
      "inputSchema": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "additionalProperties": false
      }
    }
  ]
}

The restricted sample returns “No rules triggered.” That wording is intentional: the application cannot establish whether the actual server enforces its declared boundaries.

If a manifest instead requests shell:execute without approval, the engine produces EXEC-01 at Critical review priority. A path allowlist containing / triggers SCOPE-02. Network delivery without restricted destinations triggers EGRESS-01.

These are declarations to investigate, not proof that an attack has occurred.

Keeping the review itself predictable

The application has three workspaces:

1. Review Manifest — paste/import JSON, load synthetic examples, inspect findings, filter by category/severity, and export reports.
2. Rulebook & Schema — read the supported format, rule IDs, and known limitations.
3. Test Lab — run the actual pure-engine tests in the browser and inspect pass/fail results.

Input limits include 1 MB of UTF-8 text, at most 50 tools, descriptions up to 8,000 characters, and bounded nesting. The structural validation walk uses an explicit stack so a deeply nested input cannot overflow a recursive call stack.

Malformed remote URLs, invalid authentication types, duplicate tool names, and unsupported native mcpServers configurations are rejected. They do not receive a green result.

Editing input marks the old report stale and disables export until a new analysis completes. Failed validation clears the previous report. Re-analysis clears prior checklist selections and filters, and Reset clears the editor and review state.

Privacy has a boundary too

The review engine runs locally in client JavaScript. It does not call a model, connect to an endpoint, launch a daemon, or persist manifests in browser storage. Google AI Studio was used to build the application; the review engine requires no runtime AI API key.

Known credential patterns are masked in report evidence and metadata, including URL userinfo, sensitive query parameters, authorization tokens, assignments, and private-key blocks. Unknown metadata and the full raw manifest are omitted from exports. Markdown output escapes user-controlled text.

Redaction is best-effort. An unlabelled or novel secret may be missed. The editor intentionally shows the input, and the hosting platform's behavior is outside the engine's control. Use synthetic examples in hosted previews and inspect every export before sharing it.

What was verified

The initial AI-assisted build was followed by source review, fixes, and independent acceptance regressions.

The final checks produced:

• 43/43 pure-engine tests passing locally and in the browser Test Lab.
• A successful TypeScript check and Vite production build.
• A restricted custom manifest with zero findings.
• A synthetic risky manifest with 13 findings spanning all seven categories.
• UI checks for stale exports, invalid input, filtering, checklist reset, unsupported formats, and Reset.
• A generated Markdown report downloaded and inspected.
• A small-screen layout check with no page-level horizontal overflow.

Tests cover the implemented behavior; they do not measure protection against every attack or prove real-world detection coverage.

Where this fits

ToolTrust is useful as a review worksheet before an agent receives access. It complements source review, sandboxing, server-side authorization, runtime approval gates, and monitoring.

The permission vocabulary is custom, and unrecognized labels may not match a rule. Description checks use heuristics, and the input-schema credential rule currently examines top-level names. Nested parameters and actual runtime enforcement still need human review.

The goal is a clearer permission review, with evidence and explicit limits, before connecting a tool to an agent.