Tool schema with Pydantic
Define complex tool inputs using Pydantic BaseModel with @tool(args_schema=YourPydanticModel). This allows specifying field descriptions, defaults, and literal type options.
LangChain · Agents · all subjects
agents/tools
147 notes in this subject, read out of this brain and free to use. This is page 3 of 3.
Tool schema with JSON schema
Define tool inputs using a JSON schema dict and pass it to @tool(args_schema=schema_dict).
Reserved tool argument names
The parameter names 'config' and 'runtime' are reserved and cannot be used as tool arguments. 'config' is reserved for passing RunnableConfig to tools internally, and 'runtime' is reserved for ToolRuntime parameter (accessing state, context, store). Using these names will cause runtime errors.
Migrate from InjectedState to ToolRuntime
Replace InjectedState, InjectedStore, get_runtime(), and InjectedToolCallId with ToolRuntime for one explicit interface to state, context, store, and execution metadata.
Tool return string for human-readable results
Return a string from a tool when it should provide plain text for the model to read. The return value is converted to a ToolMessage. No agent state fields are changed unless the model or another tool does so later.
Tool return object for structured results
Return an object (dict) from a tool when it produces structured data that the model should inspect. The object is serialized and sent back as tool output. The model can read specific fields and reason over them.
Tool return multimodal content
Tools can return multimodal content as a list of dicts with 'type' and content (e.g., {'type': 'text', 'text': '...'}, {'type': 'image', 'url': '...'}). When the model supports multimodal tool results, it receives text, images, and other media in one tool result.
Tool return Command for state updates
Return a Command when the tool needs to update graph state. You can return a Command with or without including a ToolMessage. If the model needs to see that the tool succeeded, include a ToolMessage in the update using runtime.tool_call_id.
Tool return_direct short-circuits agent loop
Set return_direct=True on a tool to short-circuit the agent loop: the agent returns the tool's output immediately without sending it back through the model for further processing. If the model calls multiple tools, return_direct takes effect only when all called tools have return_direct=True.
Tool return_direct use cases
Use return_direct=True when the tool's output is the complete user-ready answer (e.g., a lookup), you want to avoid an extra model call, or you need deterministic unmodified output. Not suitable for tools whose results require reasoning, summarization, or chaining with other tool calls.
Dynamic tool selection filtering approach
When all possible tools are known at agent creation time, pre-register them and dynamically filter which ones are exposed to the model based on state, permissions, or context using middleware.
Dynamic tool selection state-based filtering
Enable advanced tools only after certain conversation milestones by filtering tools in middleware based on state values like authentication status or message count.
Dynamic tool selection store-based filtering
Filter tools based on user preferences or feature flags stored in the Store by reading store values in middleware.
Dynamic tool selection context-based filtering
Filter tools based on user permissions from Runtime Context by checking request.runtime.context values in middleware.
Runtime tool registration pattern
When tools are discovered or created at runtime (loaded from MCP server, generated based on user data, fetched from remote registry), use two middleware hooks: wrap_model_call to add dynamic tools to request, and wrap_tool_call to handle execution of dynamically added tools.
Headless tools definition and execution
Headless tools are tool definitions (name, description, argument schema) registered on the server with the agent, while the implementation is registered only on the client and executed after an interrupt/resume handshake. This allows work to run where the user's app runs (typically the browser) rather than inside the process.
Headless tool use cases
Use headless tools when work depends on environment, device, or UI that only exists on the client: browser APIs (geolocation, IndexedDB, clipboard, canvas), privacy/locality (data stays on device), latency (no extra server round trip), or structured safe effects.
Headless tool Python implementation
In Python, create a headless tool by calling tool(...) with only name, description, and args_schema (no implementation function). This returns a HeadlessTool with no .implement() API on the Python side.
Headless tool JavaScript implementation
In JavaScript, define a tool with tool({name, description, schema}) (metadata and validation only, no server-side runner), then attach real behavior with .implement(async (args) => {...}). Put definitions and implementations in separate modules so server loads definition only.
Headless tool execution flow
When model issues tool call for headless tool, run interrupts instead of executing locally. App can inspect payload, perform action in right environment (browser, another service, human review), then resume graph with tool result.
Headless tool onTool callback
Use optional onTool callback to observe lifecycle events (start, success, error) for UI feedback such as spinners or toasts.
Tool creation with @tool decorator
The simplest way to create a tool in Python is with the @tool decorator. The function's docstring becomes the tool's description that helps the model understand when to use it. Type hints are required as they define the tool's input schema.
Prebuilt tools and toolkits availability
LangChain provides a large collection of prebuilt tools and toolkits for common tasks like web search, code interpretation, database access, and more. See the tools and toolkits integration page for complete list organized by category.
Tool creation in JavaScript with zod schema
In JavaScript, create a tool by importing the tool function from langchain and using zod to define the tool's input schema. Pass a handler function, name, description, and zod schema object.
Tool definition for voice agents
Voice agent tools are defined as functions or async functions. In Python, tools are regular functions added to the agent via the tools parameter. In TypeScript, tools are created using the tool() function with schema defined via Zod validation. Each tool needs a name, description, and input schema.
Tool decorator for defining agent tools
Tools are defined using the @tool decorator which takes a function with type hints. The function name becomes the tool name, docstring becomes the tool description, and parameter types and descriptions are automatically extracted. In JavaScript/TypeScript, the tool function is called with async implementation and a configuration object containing name, description, and Zod schema.
Tools parameter in agent definition
Pass tools in the `tools` list (Python) or `tools` array (JavaScript) to let the agent call application logic or external services. Define tools in local modules, import them into the agent entry, and add them to the definition. Alternatively, add tools from remote MCP servers without importing them into the agent entry using MCP connectors.