A tool use policy defines the boundaries within which a model can invoke tools. It tells the model which tools are available, when they should be used, when they must not be used, and how to handle failures gracefully.
How it works
Categorize tools -- group tools by sensitivity and purpose (e.g., read-only, write, admin).
Set policies per category -- define rules for each group: always allowed, requires confirmation, blocked.
Define error behaviors -- specify what the model should do on timeout, auth failure, rate limit, or not-found.
Evaluate and enforce -- at runtime, check each tool call against the policy before executing.
Policy categories
Always-allowed: Read-only queries, information retrieval, non-destructive operations.
Approval-required: Actions that modify state, send messages, or incur cost.
Context-dependent: Tools that should be used only when specific conditions are met.
Blocked: Tools that are never available to the model regardless of the situation.
Failure handling
Timeout: "The tool did not respond in time. Try a simpler approach or ask the user."
Auth error: "You do not have permission to use this tool. Suggest an alternative."
Rate limit: "This tool is rate-limited. Wait and retry, or use a different approach."
Not found: "The requested resource was not found. Verify the parameters or query."
Build This Pattern
Copy this prompt and paste it into Claude Code, OpenCode, Codex, or Cursor to implement this pattern.
Build a tool use policy system for safe and controlled tool execution.
ROLE: You are a tool governance system that defines allow/block/approval-required rules for tools, managing rate limits, failure behavior, and conflict resolution.
CONSTRAINTS:
- Three policy categories: allowed (auto-approve), approval-required (human review), blocked (never execute)
- Each tool has rate limits, timeout settings, and failure behavior configuration
- Tool conflicts: when two tools could answer, select based on confidence and relevance
- Tool cascade: when one tool's output feeds another, validate intermediate results
- All tool invocations must be logged with caller, params, result, and latency
TOOL CALLING:
- Use function calling for: define_tool_policy(tool_name, policy_data), check_policy(tool_name, caller_id?), execute_with_policy(tool_name, params, caller_id?), get_policy_violations(date_range?)
- Each tool returns structured JSON with policy data and metadata
STRUCTURED OUTPUT:
- Tool policy must return JSON: { tool_name: string, category: 'allowed' | 'approval_required' | 'blocked', rate_limit: { max_calls: number, window_seconds: number }, timeout_ms: number, failure_behavior: 'retry' | 'fallback' | 'fail', allowed_parameters: string[], blocked_parameters: string[] }
- Policy check must return JSON: { tool_name: string, caller_id: string, allowed: boolean, reason?: string, rate_limit_remaining: number, approval_required: boolean }
- Execution result must return JSON: { tool_name: string, params: Record<string, any>, result: any, status: string, latency_ms: number, policy_compliant: boolean, violations?: string[] }
- Violations report must return JSON: { total_violations: number, by_tool: Record<string, number>, by_type: Record<string, number>, recent_violations: [{ tool: string, type: string, timestamp: string }] }
CHAIN OF THOUGHT:
- Policy definition: categorize tool → set rate limits → configure failure behavior → define parameters
- Policy check: receive request → verify caller permissions → check rate limits → validate parameters
- Execution: apply policy constraints → execute tool → monitor for violations → log results
- Conflict resolution: identify competing tools → evaluate confidence → select best option → document decision
FEW-SHOT EXAMPLES:
Policy: { tool_name: 'send_email', category: 'approval_required', rate_limit: { max_calls: 10, window_seconds: 3600 }, timeout_ms: 30000, failure_behavior: 'retry', allowed_parameters: ['to', 'subject', 'body'], blocked_parameters: ['bcc'] }
Check: { tool_name: 'send_email', caller_id: 'crm-agent', allowed: true, rate_limit_remaining: 8, approval_required: true }
Violation: { tool: 'send_email', type: 'rate_limit_exceeded', timestamp: '2025-01-15T14:30:00Z' }
EVALUATION CRITERIA:
- Policy enforcement: percentage of tool calls that comply with defined policies
- Rate limit effectiveness: percentage of rate limit violations prevented
- Conflict resolution quality: percentage of tool conflicts resolved optimally
- Logging completeness: percentage of invocations with complete audit logs
The system should: 1) Define tool categories with allow/block/approval-required rules, 2) Each tool has policy: allowed parameters, rate limits, failure behavior, 3) Tool failures should produce structured error types (timeout, auth, rate-limit, not-found) with fallback actions, 4) Handle tool conflict (two tools could answer), 5) Handle tool cascade (one tool output feeds another), 6) Handle tool refusal, 7) Log every tool invocation with caller, params, result, latency, 8) Verify policy enforcement for each tool category.