OpenWikilangchain-ai/langchain

Javascript Tools

Purpose and Scope

Tools are the agent primitive LangChain uses when an application must do something beyond generating text. A tool gives the model a stable name, a model-facing description, a structured argument contract, and executable behavior. In an agent loop, the model emits a tool call, the runtime matches that call to an available tool, validates the provided arguments, runs the tool, and sends the result back as a tool message. The public tool package states the core design directly: tools are classes an agent uses to interact with the world, and the description helps the agent choose the right tool for the job.

Sources: libs/core/langchain_core/tools/init.py, libs/core/langchain_core/tools/base.py

The JavaScript Deep Agents docs describe passing custom tools, LangChain tools, and MCP-discovered tools to an agent through a tool list. The source-backed contract here explains the shared LangChain mechanics behind that experience: conversion helpers turn functions and runnables into tools, renderer helpers produce model-readable tool descriptions, retriever adapters expose knowledge lookup as a tool, and OpenAI-style parsers normalize provider tool-call payloads. This lets application authors reason about local functions, retrieval tools, partner integrations, and externally hosted capabilities with one common vocabulary.

Sources: libs/core/langchain_core/tools/convert.py, libs/core/langchain_core/tools/render.py, libs/core/langchain_core/output_parsers/openai_tools.py

Relevant Source Files

  • libs/core/langchain_core/tools/__init__.py - Defines the public import surface for tool primitives, including base classes, conversion helpers, renderers, retriever adapters, and concrete tool types.
  • libs/core/langchain_core/tools/base.py - Provides base utilities, schema annotation support, callback-related filtered arguments, tool exceptions, and supported tool message block type constants.
  • libs/core/langchain_core/tools/convert.py - Implements the overloaded tool helper for decorator usage, direct callable conversion, named runnable conversion, schema inference, response format selection, and metadata.
  • libs/core/langchain_core/tools/render.py - Renders tool names, descriptions, function signatures, and argument schemas as plain text for prompts and debugging surfaces.
  • libs/core/langchain_core/tools/retriever.py - Adapts a retriever into a structured tool with synchronous and asynchronous execution paths and an optional document artifact response.
  • libs/core/langchain_core/output_parsers/openai_tools.py - Parses OpenAI-style raw tool-call payloads into LangChain tool-call objects or invalid tool-call records.

Core Primitives

The safest way to understand LangChain tools is to separate the authoring contract from the execution loop. Authors define capabilities with names, descriptions, and inputs. Agent runtimes decide when to call those capabilities. Model providers may represent calls differently, but LangChain normalizes them into tool-call objects and tool messages. The public namespace collects the concepts a developer normally imports: base abstractions, simple and structured tool classes, conversion functions, rendering utilities, retriever helpers, injected argument markers, and exceptions. That namespace is intentionally broad because tools sit at the boundary between agents, callbacks, schemas, and external systems.

Sources: libs/core/langchain_core/tools/init.py, libs/core/langchain_core/tools/base.py

A normal callable is often the best starting point. The conversion helper supports decorator and direct-call forms, optional explicit naming, conversion of runnables, custom descriptions, direct-return behavior, custom argument schemas, schema inference, docstring parsing, invalid-docstring policy, response format selection, and extra metadata. Type hints matter because inferred schemas depend on the function signature and annotations. Descriptions also matter because they are not only human documentation; they are selection hints that guide the model when multiple tools could plausibly answer the same user request.

Sources: libs/core/langchain_core/tools/convert.py, libs/core/langchain_core/tools/base.py

A tool should be designed as a narrow capability rather than a vague endpoint. Prefer names that describe the action, argument names that reflect the domain, and descriptions that explain when the tool should be used. The base utilities include support for extracting field descriptions from annotated types and Google-style docstrings, so schema information can carry useful guidance beyond simple type names. This becomes important when a tool list mixes local business logic, retriever tools, integration packages, and MCP tools discovered from another process, because the model must compare all of them through the same selection surface.

Sources: libs/core/langchain_core/tools/base.py, libs/core/langchain_core/tools/render.py

Tool Calling and Tool Messages

A tool call is the structured request emitted by a model or agent. The OpenAI-style parser expects a raw payload with a function object containing a function name and JSON-encoded arguments, plus an optional provider identifier. It returns a LangChain-shaped call with the name and parsed arguments, and it can include the identifier so downstream code can connect a result to the exact request that produced it. Parameterless tools are handled deliberately: when arguments are absent or empty, the parser produces an empty argument object instead of treating the call as invalid.

Sources: libs/core/langchain_core/output_parsers/openai_tools.py

Parsing behavior affects streaming, frontend rendering, retries, and observability. When partial parsing is enabled, incomplete or not-yet-decodable JSON can return no call until enough data is available. When partial parsing is disabled, invalid JSON raises an output parser exception that includes the function name and the raw argument text that failed to decode. A separate helper preserves malformed provider output as an invalid tool-call record containing the raw name, raw argument string, identifier, and error message. That preservation is useful because UIs and traces can explain a failure without discarding the original model output.

Sources: libs/core/langchain_core/output_parsers/openai_tools.py

Tool results flow back as tool messages, and LangChain’s base module shows that tool message content is broader than plain text. Supported block types include text, image references, JSON, search results, custom tool-call output, documents, and files. This maps cleanly to frontend tool-calling patterns where an AI message contains tool calls with names, arguments, and identifiers, the backend executes those calls, and the client assembles running, finished, or errored tool-call state. Keeping identifiers stable through this loop is what lets a UI render progress and attach a result to the correct call.

Sources: libs/core/langchain_core/tools/base.py, libs/core/langchain_core/output_parsers/openai_tools.py

Authoring and Conversion Flow

For a local tool, start with the smallest operation that should be callable by an agent, such as weather lookup, search, database access, or a domain-specific service request. Convert the callable with the tool helper, provide an explicit name and description when the function name is not sufficient, and inspect the generated argument schema before exposing it to an autonomous loop. If the result should end the loop immediately, use the direct-return option. If the result includes both user-visible content and a secondary artifact, select the content-and-artifact response format and make the return shape match that contract.

Sources: libs/core/langchain_core/tools/convert.py

from langchain_core.tools import tool
 
@tool(description="Look up a city weather report")
def get_weather(city: str) -> str:
    return f"Weather for {city}: sunny"

Retriever tools are a specialized bridge between retrieval-augmented generation and agent tool calling. The retriever adapter creates a structured tool with a single query field, invokes the retriever with callback configuration, formats returned documents through a prompt, joins the formatted documents with a separator, and returns either only message content or a pair containing content and document artifacts. The asynchronous implementation mirrors the synchronous path, which means the same public tool can be used by applications that await retrieval, stream intermediate state, or preserve source documents for later inspection.

Sources: libs/core/langchain_core/tools/retriever.py

Rendering, Review, and Debugging

Some agents, prompts, and debugging tools need a plain-text view of the available tool set. The renderer module defines a renderer as a callable that receives a list of base tools and returns a string. One helper prints each tool’s name and description, including the underlying function signature when the tool has a function. The other helper appends the argument schema. These helpers are intentionally simple, but they reveal an important practice: before production use, review the exact model-facing text and verify that each tool is distinguishable, concise, and specific.

Sources: libs/core/langchain_core/tools/render.py

Rendering is also a practical way to catch tool-design problems early. If two descriptions overlap, if required inputs are hidden behind unclear argument names, or if a broad tool competes with a more specific one, the model may choose inconsistently. Review rendered local tools beside retriever tools and externally discovered tools, then adjust names, descriptions, and schemas until the intended choice is obvious. This review is especially valuable for JavaScript Deep Agents that combine local functions with MCP server tools, because server-provided capabilities may follow naming conventions that differ from application-owned tools.

Sources: libs/core/langchain_core/tools/render.py, libs/core/langchain_core/tools/retriever.py

MCP, External APIs, and Agent Integration

MCP tools differ from local tools mainly in ownership and discovery. A local tool is defined inside the application process, while an MCP server exposes tools over an external protocol and the agent discovers them at startup. The official JavaScript docs describe MCP as a way to add filesystem, API, database, and other server-hosted capabilities without modifying the agent itself. From LangChain’s perspective, the same conceptual contract still applies: each capability needs a name, a description, structured arguments, an execution result, and a tool message linked to the original call.

Use the source of a tool to reflect operational boundaries. Keep sensitive in-process business logic local when it needs direct access to application services, credentials, or typed objects. Use retriever tools when the operation is document lookup and returned documents may be useful artifacts. Use MCP when a capability is better owned by a separate server or shared across projects. For HTTP APIs and OpenAPI-backed operations, treat the generated or wrapped operation like any other tool: validate the schema, make side effects explicit in the description, and preserve call identifiers so approvals, logs, and UI cards can reason about what happened.

Sources: libs/core/langchain_core/tools/convert.py, libs/core/langchain_core/tools/retriever.py, libs/core/langchain_core/output_parsers/openai_tools.py

Compact API Reference

  • tool(...) converts callables and runnables into LangChain tools. Important options include description, return_direct, args_schema, infer_schema, response_format, parse_docstring, error_on_invalid_docstring, and extras.
  • create_retriever_tool(...) wraps a retriever as a structured tool. Important inputs include retriever, name, description, document_prompt, document_separator, and response_format.
  • RetrieverInput is the retriever tool input schema and contains the query field.
  • render_text_description(...) renders tool names, optional function signatures, and descriptions.
  • render_text_description_and_args(...) renders tool descriptions together with argument schemas.
  • parse_tool_call(...) parses one OpenAI-style raw call with partial, strict, and return_id controls.
  • parse_tool_calls(...) parses a list of raw calls and aggregates parsed results.
  • make_invalid_tool_call(...) preserves malformed provider output as an invalid tool-call object.

Sources: libs/core/langchain_core/tools/convert.py, libs/core/langchain_core/tools/render.py, libs/core/langchain_core/tools/retriever.py, libs/core/langchain_core/output_parsers/openai_tools.py

Next Steps

Start with one typed local tool, render it, and review the text as if you were the model choosing among alternatives. Add retriever tools when the agent needs knowledge lookup, and decide whether document artifacts should be retained for UI or audit workflows. If your frontend renders live tool progress, preserve tool-call identifiers from the AI message through the tool result. When capabilities come from MCP or API-backed integrations, hold them to the same naming, schema, and description standards as local tools.

Related pages: agents-overview, agent-configuration-instructions, retrievers, mcp, openapi-integration, headless-tools-and-tool-calling.

Ask a question...