Tool Access Control

Control which agents can use which tools

Tool access control enforces the principle of least privilege. Each agent only has access to the tools it needs.

Why Control Tool Access?

• Security — Prevent agents from accessing sensitive operations
• Reliability — Reduce blast radius of agent errors
• Compliance — Audit which agents used which tools

Basic Usage

from splinter.control import ToolAccessController

ctrl = ToolAccessController()

# Researcher can search and read
ctrl.set_allowed_tools("researcher", ["web_search", "read_file"])

# Writer can only write
ctrl.set_allowed_tools("writer", ["write_file"])

# Check access
ctrl.check_access("researcher", "web_search")   # ✓ OK
ctrl.check_access("researcher", "delete_file")  # ✗ Raises ToolAccessDeniedError

Tool Permissions

Fine-grained permissions:

from splinter.control import ToolAccessController, ToolPermission

ctrl = ToolAccessController()

# Read-only access to files
ctrl.add_permission("researcher", ToolPermission(
    tool="file_*",           # Glob pattern
    actions=["read"],        # Only read
    paths=["./data/*"],      # Only in data dir
))

# Full access to specific directory
ctrl.add_permission("writer", ToolPermission(
    tool="file_*",
    actions=["read", "write", "delete"],
    paths=["./output/*"],
))

Tool Registry

Register available tools:

from splinter.control import ToolRegistry

registry = ToolRegistry()

registry.register("web_search", 
    description="Search the web",
    risk_level="low",
)

registry.register("delete_file",
    description="Delete a file",
    risk_level="high",
    requires_approval=True,
)

# Get tool info
info = registry.get_tool("delete_file")
print(f"Risk level: {info.risk_level}")  # "high"

Denying Access

from splinter.exceptions import ToolAccessDeniedError

try:
    ctrl.check_access("researcher", "delete_file")
except ToolAccessDeniedError as e:
    print(f"Access denied: {e.agent_id} cannot use {e.tool}")
    print(f"Allowed tools: {e.allowed_tools}")

Dynamic Access

Change permissions at runtime:

# Add a tool
ctrl.allow_tool("researcher", "send_email")

# Remove a tool
ctrl.deny_tool("researcher", "send_email")

# Temporarily elevate permissions
with ctrl.temporary_access("researcher", ["admin_panel"]):
    # Agent has admin access here
    pass
# Access revoked after context

Audit Trail

Track tool usage:

ctrl = ToolAccessController(audit=True)

# Later, get audit log
log = ctrl.get_audit_log()
# [
#   {"agent": "researcher", "tool": "web_search", "time": "...", "allowed": True},
#   {"agent": "researcher", "tool": "delete_file", "time": "...", "allowed": False},
# ]

Best Practices

Start with minimal permissions

Give agents only the tools they need. Add more if required.

Use glob patterns for related tools

file_* matches file_read, file_write, file_delete.

Audit high-risk tools

Always log usage of tools that can modify data or access sensitive systems.

Review permissions regularly

Agents evolve. Their permissions should too.