Why You Shouldn’t Use @tool in LangGraph's StateGraph Workflows

Introduction

LangGraph has introduced a more structured approach to state management in AI workflows, shifting away from previous agentic patterns. One major question that arises when using tools like Tavily Search is whether to annotate functions with @tool. In this article, we'll explore why @tool is unnecessary in a StateGraph, why this method is superior to previous integrations, and whether ToolNode should be deprecated.

📌 Code Example: You can follow along with the full code here: GitHub Repository

The Role of StateGraph in LangGraph

StateGraph provides a structured way to manage state transitions in LangGraph workflows. Instead of relying on autonomous decision-making like in LangChain agents, StateGraph ensures deterministic execution, where each function updates a shared state dictionary.

This structured approach allows developers to:

• Control workflow execution explicitly, avoiding unpredictable agent behavior.
• Manage state updates more effectively by modifying only relevant parts of the state.
• Improve maintainability by keeping functions simple and avoiding tool registration overhead.

📖 Official Documentation: Updating State from Tools

Why You Should Not Use @tool in search_with_tavily

In LangChain’s agent-based models, @tool is used to register functions dynamically so that an LLM can decide when and how to invoke them. However, StateGraph works differently:

❌ @tool is unnecessary because:

• search_with_tavily is explicitly added as a node (workflow.add_node("search", search_with_tavily)). LangGraph directly calls this function, making @tool redundant.
• @tool is primarily for LLM-based decision-making, while StateGraph follows deterministic execution.
• The function does not need to be listed as an available tool, since it’s part of a controlled flow.

Using @tool in this case adds no benefit and could cause confusion about how the function is used.

Why This is Better Than Previous Tavily Integrations

🔍 Comparing with LangChain’s Tool Integration

LangChain provides an integration for Tavily Search (Docs), which allows an LLM agent to decide when to call the search function. However, this approach has several drawbacks:

Feature LangChain Agent + Tavily Tool LangGraph StateGraph Execution Control LLM decides dynamically Deterministic State Management Implicit Explicit & Controlled Complexity Higher Lower Reproducibility Unpredictable Predictable

LangGraph’s approach improves reliability, maintainability, and control by structuring state updates explicitly.

The Evolution of NodeTool in LangGraph

LangGraph previously introduced NodeTool as a way to streamline tool integration within workflows. However, this feature has since been replaced due to the need for more flexible and maintainable state management. The transition away from NodeTool allows for greater customization and direct state modifications using state reducers and tools.

🚀 Why NodeTool Was Deprecated:

• Originally introduced to simplify invoking external APIs and tools, but it lacked flexibility.
• Managing dynamic state updates was difficult when using NodeTool.
• The new approach provides better control over agent behavior, state persistence, and modular tool interactions.

Should ToolNode Be Deprecated?

Given the improvements in state management and workflow control, ToolNode (similar to NodeTool) is becoming obsolete. Instead of relying on predefined tool execution, developers can now modify state explicitly in a structured manner, eliminating the need for dedicated tool nodes.

Conclusion

If you’re transitioning to LangGraph, stop using @tool in stateful workflows. Instead, rely on StateGraph to define deterministic state updates, ensuring clarity, maintainability, and full execution control.

🔗 Further Reading: Updating State from Tools