Skip to main content
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

Give agents only the tools they need. Add more if required.
Always log usage of tools that can modify data or access sensitive systems.
Agents evolve. Their permissions should too.