@wrap_tool_call: Reference Guide

What is @wrap_tool_call?

@wrap_tool_call is a LangChain agent middleware decorator that intercepts tool call objects before the corresponding @tool-decorated function is executed. It is the security and governance layer for tool use: you can inspect the tool name, validate its arguments, enforce access control rules, log every call for auditing, apply rate limits per tool, or outright block calls to forbidden tools by raising an exception.

The decorated function receives a tool call object with at minimum a .name attribute (the tool's registered name) and an .args attribute (the dict of arguments the model supplied). It must return the call object to allow execution to proceed, or raise an exception to abort the tool call. Modifying .args before returning allows you to sanitize or constrain the arguments — for example, capping a limit parameter the model set too high, or escaping SQL injection attempts in a query string argument.

The hook fires for every tool call in a multi-call turn. If the model decides to call three tools simultaneously (as happens with parallel tool calling on OpenAI models), @wrap_tool_call fires three times — once per call object — before any of them executes. This gives you a consistent enforcement point regardless of whether the model batches tool calls. For read-only tools (search, lookup), a logging-only hook is sufficient; for write tools (file operations, database writes, API mutations), validate and block in the hook before execution, since rolling back a completed write is far harder than preventing it.

Use Cases

• • Validate calls
• • Rate limit
• • Audit logs
• • Security checks
• • Log usage
• • Route calls

Key Features

• ✓ Intercept calls
• ✓ Parameter inspection
• ✓ Error handling
• ✓ Logging
• ✓ Conditional execution
• ✓ Validation

When NOT to Use

Notes

Import

from langchain.agents import wrap_tool_call

How to Apply

@wrap_tool_call
def validate(call):
    if call.name == 'delete':
        if not is_safe(call.args):
            raise ValueError('Unsafe')
    return call

What It Enables

• ✓ Call validation
• ✓ Monitoring
• ✓ Rate limiting
• ✓ Security

Code Examples

from langchain.agents import wrap_tool_call
@wrap_tool_call
def validate(call):
    print(f'Tool call: {call.name}({call.args})')
    return call

from langchain.agents import wrap_tool_call
FORBIDDEN_TOOLS = {"delete_file", "drop_table"}
@wrap_tool_call
def security_guard(call):
    if call.name in FORBIDDEN_TOOLS:
        raise PermissionError(f"Tool {call.name!r} is not allowed")
    return call

from langchain.agents import wrap_tool_call
import time
_rate = {}
@wrap_tool_call
def rate_limit_tools(call):
    now = time.time()
    last = _rate.get(call.name, 0)
    if now - last < 1.0:  # 1 call per second per tool
        raise RuntimeError(f"{call.name} called too frequently")
    _rate[call.name] = now
    return call

Integration Patterns

Common Mistakes

Related LangChain References

Browse the full LangChain API reference index to explore more classes, methods, and decorators, or start with the LangChain introduction tutorial for end-to-end context on building with @wrap_tool_call and the wider framework.

@wrap_tool_call FAQ