Tool Authorization

Ensure agents can access only approved tools and operations through policy-driven allowlists, role-based access control, and permission checks.

Overview

Tool authorization prevents unauthorized agent actions such as database modifications, shell execution, or external API misuse. Policies are defined in YAML and enforced through hooks that run before tool execution in your agent framework.

Use this guardrail when agents have access to multiple tools and you need to restrict what each role or user can invoke at runtime.

How It Works

1. Define allowed and denied tools in your policy YAML.
2. Assign tool permissions per role using allowed_tools.
3. Mark high-risk tools as sensitive_tools requiring explicit approval metadata.
4. Call before_tool_call() in an agent hook before the tool executes.
5. Blocked calls return a clear error without running the underlying tool.

Configuration

Enable Tool Authorization

guardrails:
  tool_authorization:
    enabled: true

    # Globally blocked tools — no role can access these
    denied_tools:
      - execute_shell

    # Sensitive tools require explicit approval metadata
    sensitive_tools:
      - delete_record

    roles:
      analyst:
        allowed_tools:
          - search_web
          - calculator

      engineer:
        allowed_tools:
          - search_web
          - calculator
          - delete_record

      admin:
        allowed_tools:
          - search_web
          - calculator
          - delete_record
          - execute_shell   # still blocked globally via denied_tools

Parameters

Option	Type	Description
enabled	bool	Enable tool authorization
denied_tools	list	Tools blocked for all roles, regardless of allowlist
sensitive_tools	list	Tools requiring metadata={"approved": true} to execute
roles	dict	Role definitions with per-role allowed_tools lists

Policy Evaluation Order

1. Denied tools — If the tool is in denied_tools, access is blocked for every role.
2. Role allowlist — The caller's role must appear in roles and include the tool in allowed_tools.
3. Sensitive tools — If the tool is in sensitive_tools, metadata={"approved": true} must be passed to before_tool_call().

Usage with Agent Hooks

Tool authorization is enforced through GuardrailSystem hooks, not automatically inside LLMRails. Integrate the hook into your agent graph before tool execution.

Initialize Guardrails

from elsai_guardrails.guardrails import GuardrailSystem, ToolCallCheckResult
from elsai_guardrails.guardrails.guardrail_policy import GuardrailPolicy

guardrails = GuardrailSystem(
    guardrail_policy=GuardrailPolicy.from_file("config.yaml"),
)

Check Before Tool Execution

result: ToolCallCheckResult = guardrails.before_tool_call(
    tool_name="delete_record",
    user_role="engineer",
    metadata={"approved": False},
    raise_on_block=False,
)

if result.passed:
    print(f"Allowed: {result.tool_name} for role {result.user_role}")
else:
    print(f"Blocked: {result.error}")

LangGraph Integration Pattern

Insert an authorization node between the LLM and tool execution:

def authorization_node(state: AgentState):
    last_message = state["messages"][-1]
    blocked_messages = []

    for call in last_message.tool_calls:
        result = guardrails.before_tool_call(
            tool_name=call["name"],
            user_role=state.get("user_role", "unknown"),
            raise_on_block=False,
        )

        if not result.passed:
            blocked_messages.append(
                ToolMessage(
                    tool_call_id=call["id"],
                    content=f"GUARDRAIL BLOCKED: {result.error}",
                )
            )

    return {"messages": blocked_messages} if blocked_messages else {}

Recommended graph flow:

agent → authorization → tools → agent

When a tool call is blocked, inject a ToolMessage with the guardrail error and route back to the agent so the LLM surfaces the denial to the user.

Example Scenarios

Scenario	Role	Tool	Result
Allowed calculator use	analyst	calculator	✅ Allowed
Globally denied shell	admin	execute_shell	❌ Blocked (denied_tools)
Role not permitted	analyst	delete_record	❌ Blocked (not in allowlist)
Sensitive without approval	engineer	delete_record	❌ Blocked (approved=False)
Unknown role	intern	search_web	❌ Blocked (role not defined)

Best Practices

1. Use denied_tools for hard blocks — Reserve the global deny list for irreversible or high-risk operations like shell execution.
2. Keep role allowlists minimal — Grant only the tools each role needs (principle of least privilege).
3. Gate sensitive tools with metadata — Require explicit approval for destructive operations like record deletion.
4. Hook before execution — Always run authorization in a pre-tool node; never rely on the LLM to self-police tool access.
5. Echo guardrail messages — Instruct the agent to repeat GUARDRAIL BLOCKED: messages verbatim so users see the actual policy reason.

Next Steps

• Rate Limiting & Abuse Prevention — Limit requests, tool calls, and execution time
• GuardrailSystem — Core API reference
• Guardrails Configuration — Full configuration reference