Tool Calling in LangGraph

Define Your Tools

Tools in LangGraph are Python functions annotated with metadata that tells the LLM what the tool does, what inputs it expects, and what it returns. LangChain's tool decorator is the simplest way to create tools. You write a regular Python function with a docstring, add the decorator, and the framework extracts the function name, description, and parameter schema automatically.

For more control, you can define tools as StructuredTool instances with explicit descriptions, input schemas using Pydantic models, and custom output formatting. The structured approach is better for complex tools where the auto-extracted schema does not provide enough detail for the LLM to use the tool correctly.

Good tool design is critical for agent reliability. The tool's name should clearly describe what it does. The docstring should explain when the LLM should use it and what information it provides. Parameter descriptions should specify valid input formats and constraints. Ambiguous or poorly described tools lead to incorrect tool calls, which cascade into incorrect agent outputs.

Bind Tools to the LLM

After defining your tools, bind them to the LLM model instance using the bind_tools method. This sends the tool schemas to the model as part of every prompt, enabling the model to request tool calls in its responses. The binding happens once when you set up the model, and the tools are available for every subsequent invocation.

The model does not execute tools itself. It generates a structured request specifying which tool to call and what arguments to provide. The LangGraph framework intercepts this request and routes execution to the tool node, which actually runs the tool function and returns the result.

You can bind different sets of tools to different model instances within the same graph. A research agent might have web search and document retrieval tools, while a data agent has SQL query and calculation tools. This tool scoping keeps each agent's capabilities focused and reduces the chance of the LLM selecting an inappropriate tool.

Build the Tool-Calling Loop

The tool-calling loop is the core pattern in most LangGraph agents. It consists of two nodes and a conditional edge. The LLM node sends the conversation to the model and receives a response. The conditional edge checks whether the response contains tool call requests. If it does, execution routes to the tool node. If it does not, execution ends with the model's final response.

The tool node executes the requested tools and adds the results to the conversation as tool messages. An edge then routes back to the LLM node, where the model sees the tool results and decides what to do next. It might request another tool call, or it might produce a final response. This cycle repeats until the model generates a response without any tool calls.

LangGraph's prebuilt ToolNode handles the common case automatically: it receives tool call messages, looks up the matching tool functions, executes them, and returns the results as properly formatted tool messages. For most use cases, the prebuilt ToolNode eliminates the need to write custom tool execution logic.

Set a maximum iteration limit on the loop to prevent infinite cycling. If the model keeps requesting tools without converging on a final answer, the limit forces termination with an appropriate error message. In production, five to ten iterations is a common limit, though the right number depends on your specific workflow.

Handle Tool Errors

Tools fail. APIs time out, databases return errors, external services go down, and models sometimes request tool calls with invalid arguments. Robust error handling is essential for production agents.

The simplest approach is to catch exceptions in your tool functions and return error descriptions as the tool result rather than letting exceptions propagate. The LLM receives the error description and can adapt its approach, perhaps trying different arguments or choosing a different tool. This keeps the agent loop running and often leads to successful recovery.

For more sophisticated handling, add conditional edges that detect tool errors in the state and route to error-specific nodes. An error handler node might retry the tool with modified arguments, switch to a fallback tool, log the error for monitoring, or escalate to human review via an interrupt gate.

Track tool call patterns in production to identify tools that fail frequently or take too long. This data helps you improve tool reliability and set appropriate timeout values. LangSmith tracing provides detailed visibility into tool call success rates, latency distributions, and error patterns.