Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getunbound.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Tool Policy Hooks endpoint lets you enforce your organization’s tool policies on agent tool calls. Before your agent executes a tool — whether it’s a terminal command, an MCP tool, or any other action — send a request to this endpoint to check whether the call should be allowed, denied, or requires user approval. Any agent framework or custom application can integrate with it. Policies are configured at gateway.getunbound.ai/policies/tool-policies.

​
Endpoint

POST /v1/hooks/pretool

​
Authentication

Include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Request Body

ParameterTypeRequiredDescription
conversation_idstringYesUnique identifier for the conversation or session
modelstringYesThe model being used
event_namestringYespre_tool_use for tool policy checks, user_prompt for prompt guardrails
unbound_app_labelstringYesYour application identifier (e.g., openclaw, claude-code, cursor, or a custom label)
pre_tool_use_dataobjectYesDetails about the tool being invoked (see below)
messagesarrayNoConversation messages for context

​
pre_tool_use_data Object

ParameterTypeRequiredDescription
tool_namestringYesName of the tool. Use Bash, Shell, or exec for terminal commands. For MCP tools, use the full name (e.g., mcp__slack__send_message)
commandstringConditionalThe shell command string. Required when tool_name is Bash, Shell, or exec
metadataobjectNoAdditional metadata. For MCP tools, include mcp_server and mcp_tool

​
Response

FieldTypeDescription
decisionstringallow, deny, or ask
reasonstringPresent when decision is deny or ask. Human-readable explanation

​
Decision Values

DecisionMeaningRecommended Action
allowTool call is permittedProceed with execution
denyTool call is blocked by policyDo not execute. Show the reason to the user
askTool call requires user confirmationPrompt the user for approval before executing. If your agent has no confirmation UI, treat as allow based on your security posture

​
How It Works

The endpoint handles two types of tools differently: Terminal commands (Bash, Shell, exec): The command is automatically classified and matched against your configured terminal command policies. MCP tools: The mcp_server and mcp_tool from metadata are matched against your MCP tool policies. Other tools: Tools that don’t match a terminal command or MCP tool pattern return allow.

​
Examples

​
Terminal Command (Blocked)

curl -X POST 'https://api.getunbound.ai/v1/hooks/pretool' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "session-123",
    "model": "claude-sonnet-4-20250514",
    "event_name": "pre_tool_use",
    "unbound_app_label": "my-agent",
    "pre_tool_use_data": {
      "tool_name": "Bash",
      "command": "rm -rf /tmp/data",
      "metadata": {}
    },
    "messages": [
      {"role": "user", "content": "clean up temp files"}
    ]
  }'
Response: 
{
  "decision": "deny",
  "reason": "This command is blocked by your organization's policy."
}

​
Terminal Command (Allowed)

curl -X POST 'https://api.getunbound.ai/v1/hooks/pretool' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "session-123",
    "model": "claude-sonnet-4-20250514",
    "event_name": "pre_tool_use",
    "unbound_app_label": "my-agent",
    "pre_tool_use_data": {
      "tool_name": "Bash",
      "command": "ls -la /tmp",
      "metadata": {}
    },
    "messages": []
  }'
Response: 
{
  "decision": "allow"
}

​
MCP Tool

curl -X POST 'https://api.getunbound.ai/v1/hooks/pretool' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "session-123",
    "model": "claude-sonnet-4-20250514",
    "event_name": "pre_tool_use",
    "unbound_app_label": "my-agent",
    "pre_tool_use_data": {
      "tool_name": "mcp__slack__send_message",
      "command": "",
      "metadata": {
        "mcp_server": "slack",
        "mcp_tool": "send_message"
      }
    },
    "messages": []
  }'
Response (depends on your configured policies): 
{
  "decision": "deny",
  "reason": "This MCP tool call is blocked by your organization's policy."
}

​
Integration Guide

To integrate tool policies into your agent framework:
  1. Before each tool execution, send a POST request to /v1/hooks/pretool with the tool details
  2. Check the decision in the response:
    • allow — execute the tool normally
    • deny — block execution and surface the reason to the user
    • ask — prompt the user for confirmation, or treat as allow if your agent has no interactive UI
  3. Handle errors gracefully — if the endpoint is unreachable, decide whether to fail open (allow) or fail closed (deny) based on your security requirements
  4. Configure policies at gateway.getunbound.ai/policies/tool-policies