From 919a832d9c16b205c06466dbe5863a893baa319c Mon Sep 17 00:00:00 2001
From: BenHavis <ben.havis1@gmail.com>
Date: Thu, 4 Dec 2025 11:07:15 -0500
Subject: [PATCH] Add ToolRuntime migration section to tools documentation

Adds a migration section explaining how older injection helpers (InjectedState, InjectedStore, get_runtime, etc.) map to the unified ToolRuntime API.
---
 src/oss/langchain/tools.mdx | 50 +++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/src/oss/langchain/tools.mdx b/src/oss/langchain/tools.mdx
index c811ff73bc..7882ab95b2 100644
--- a/src/oss/langchain/tools.mdx
+++ b/src/oss/langchain/tools.mdx
@@ -151,6 +151,56 @@ The following parameter names are reserved and cannot be used as tool arguments.
 To access runtime information, use the @[`ToolRuntime`] parameter instead of naming your own arguments `config` or `runtime`.
 :::
 
+### Migration: Older Injection Patterns → `ToolRuntime`
+
+Many earlier LangChain examples used multiple injection helpers such as
+`InjectedState`, `InjectedStore`, `get_runtime()`, or `InjectedToolCallId`.
+These patterns have now been unified under the `ToolRuntime` API.
+
+`ToolRuntime` provides a single interface for accessing:
+
+- Execution state
+- Context data
+- Long-term memory (store)
+- Streaming callbacks
+- Execution config
+- Tool call metadatakv
+
+This simplifies tool development and makes tools easier to test.
+
+#### Before (deprecated)
+
+```python
+from langchain.tools import tool, InjectedState
+
+@tool
+def summarize(state: InjectedState) -> str:
+    """Summarize the conversation."""
+    messages = state["messages"]
+    return f"Conversation length: {len(messages)} messages."
+```
+
+#### After (recommended)
+
+```python
+from langchain.tools import tool, ToolRuntime
+
+@tool
+def summarize(runtime: ToolRuntime) -> str:
+    """Summarize the conversation."""
+    messages = runtime.state["messages"]
+    return f"Conversation length: {len(messages)} messages."
+```
+
+#### Why migrate?
+
+- Unifies several older injection patterns
+- Makes tool behavior more explicit and predictable
+- Improves testability
+- Aligns with LangGraph state and context patterns
+- Avoids hidden implicit global state
+
+
 ## Accessing Context
 
 <Info>