> ## Documentation Index
> Fetch the complete documentation index at: https://splinter.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
# 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:

```python theme={null}
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

<AccordionGroup>
  <Accordion title="Start with minimal permissions">
    Give agents only the tools they need. Add more if required.
  </Accordion>

  <Accordion title="Use glob patterns for related tools">
    `file_*` matches `file_read`, `file_write`, `file_delete`.
  </Accordion>

  <Accordion title="Audit high-risk tools">
    Always log usage of tools that can modify data or access sensitive systems.
  </Accordion>

  <Accordion title="Review permissions regularly">
    Agents evolve. Their permissions should too.
  </Accordion>
</AccordionGroup>