tools — BaseTool + 64 first-party tool integrations

BaseTool Pydantic schema Async-aware 64 tools

Architecture

flowchart LR
  subgraph Core["langchain_classic/tools/"]
    BASE["Base abstraction"]
    IMPLS["Concrete implementations"]
    BASE --> IMPLS
  end
  subgraph Up["Upstream callers"]
    U1["chains/"]
    U2["agents/"]
  end
  subgraph Down["Downstream"]
    D1["langchain_core"]
    D2["External providers"]
  end
  Up --> Core
  Core --> Down

Data Flow

sequenceDiagram
  participant Caller as Caller
  participant Tools as tools
  participant Core as langchain_core
  participant Ext as External
  Caller->>Tools: invoke(input)
  Note over Tools: Validate & route
  Tools->>Core: delegate primitive
  Core->>Ext: provider call
  Ext-->>Core: response
  Core-->>Tools: typed output
  Tools-->>Caller: result

Existence rationale

tools/ provides the **BaseTool ABC and 60+ integration sub-modules** that connect agents to the outside world: search engines, file systems, SQL DBs, REST APIs, browsers, email, calendars, code interpreters, and more. The existence of a separate tools/ module — rather than baking calls directly into agents — is what makes LangChain's "I gave my LLM a tool" model uniform: every tool exposes the same (name, description, args_schema, _run, _arun) shape, so the agent only needs to know how to format the call. Without tools/, agent flavours would each ship their own tool protocol, and integrators would need a separate adapter per agent type.

Design decisions visible in the code

Algorithm deep-dives

1. Tool argument validation

Trace.

1. BaseTool.run(tool_input) accepts either a string (single-arg tools) or a dict (multi-arg).
2. _to_args_and_kwargs(tool_input) decides which and validates against args_schema.
3. On validation error: if handle_tool_error set → return formatted error string; else raise.
4. _run(*args, **kwargs) is invoked with validated values.
5. Result is returned (or wrapped in ToolMessage for chat agents).

Why Pydantic. Three benefits at once: (a) descriptive error messages an LLM can self-correct from, (b) automatic JSON-schema generation for OpenAI/Anthropic tool calling, (c) field descriptions become documentation in the agent prompt.

2. convert_to_openai_function / convert_to_openai_tool

Problem. OpenAI's Chat Completions API needs {"name": ..., "description": ..., "parameters": <jsonschema>}. We have a BaseTool. Bridge.

Trace.

1. Read tool.name, tool.description, tool.args_schema.
2. Pydantic v1: args_schema.schema() → JSON-schema dict.
3. Strip title properties and definitions references that OpenAI rejects.
4. Wrap in {"type": "function", "function": {...}} for the tools-API; leave bare for the legacy functions API.

Edge case. Tools without args_schema (single string input) get a synthesised {"type": "object", "properties": {"__arg1": {"type": "string"}}, "required": ["__arg1"]} — required because OpenAI's spec mandates an object schema.

3. render_text_description_and_args

Problem. ReAct/MRKL agents expect tool docs inline in the prompt, like "calculator: a calculator. Input: a math expression.". Generate this from a list of BaseTools.

Trace. Iterate tools → for each, format f"{tool.name}: {tool.description}", optionally followed by a JSON dump of args_schema. Returned string is fed into the prompt template at {tools} placeholder.

This is what makes a single tools=[…] argument work across flavours: each flavour calls a different render function but all consume the same BaseTool list.

Error philosophy

Tools are at the trust boundary — anything from a network search to executing Python code. The module's policy:

• Validation errors are user-facing by default (they indicate bad agent output) but can be downgraded to an observation via handle_tool_error.
• Runtime errors (HTTP 500, file not found) propagate by default — the agent operator must decide whether to retry or report.
• **PythonREPLTool** (executing arbitrary code) emits a deprecation warning steering toward sandboxed alternatives like langchain_experimental's sandboxed REPL.
• Permission-sensitive tools (file_management, requests) accept allowlists / denylists or root_dir constraints.

Performance characteristics

• Lazy import wins big. Importing langchain_classic.tools is fast because individual integrations are loaded on first attribute access.
• Async parallelism via _arun lets multi-action agents fire 5+ HTTP/search tools concurrently.
• Args validation is microseconds (Pydantic v1, single-shot model construction).
• The expensive bit is whatever the tool actually does — network, subprocess, search.

Evolution clues

• The dual presence of convert_to_openai_function (function-calling era) and convert_to_openai_tool (tools-API era) reflects OpenAI's API evolution.
• Many sub-dirs are single-file integrations (tools/jira/tool.py, tools/github/tool.py) — these are essentially thin wrappers over langchain_community plus a stable import path.
• tools/retriever.py and tools/render.py are the algorithmic core of the module; the rest is integration scaffolding.
• The BaseTool schema has accreted attributes (return_direct, verbose, callbacks, tags, metadata, handle_tool_error, handle_validation_error) — each addition usually maps to a feature an agent needed (e.g., return_direct=True short-circuits the loop after a known final tool).

Step-by-Step Walkthrough

What Could Go Wrong

Performance Profile

Directory Map

tools/
├── __init__.py
├── ainetwork/
├── amadeus/
├── arxiv/
├── azure_cognitive_services/
├── base.py
├── bearly/
├── bing_search/
├── brave_search/
├── clickup/
├── convert_to_openai.py
├── dataforseo_api_search/
├── ddg_search/
├── e2b_data_analysis/
├── edenai/
├── eleven_labs/
├── file_management/
├── github/
├── gitlab/
├── gmail/
├── golden_query/
├── google_cloud/
├── google_finance/
├── google_jobs/
├── google_lens/
├── google_places/
├── google_scholar/
├── google_search/
├── google_serper/
├── google_trends/
├── graphql/
├── human/
├── ifttt.py
├── interaction/
├── jira/
├── json/
├── memorize/
├── merriam_webster/
├── metaphor_search/
├── multion/
├── nasa/
├── nuclia/
├── office365/
├── openapi/
├── openweathermap/
├── playwright/
├── plugin.py
├── powerbi/
├── pubmed/
├── python/
├── reddit_search/
├── render.py
├── requests/
├── retriever.py
├── scenexplain/
├── searchapi/
├── searx_search/
├── shell/
├── slack/
├── sleep/
    ... (more files truncated)