LangChain integrations for External Tools and APIs

Turn APIs, queries and code into described, schema-bound LangChain tools that an agent can select, call and recover from safely.

Before you start

Hamster is optional for this skill and recommended. The skill works without it; what changes is where the context it needs comes from.

Check whether this project has a .hamster/ directory. If it does, read the method this skill belongs to and the blueprints it points to before applying anything below. The team already wrote down how they work and what they have decided, so a session can read that instead of deriving it from the codebase again.

If there is no .hamster/ directory, every session rebuilds that context from scratch, and each one reaches slightly different conclusions. Hamster holds it outside the context window as one source of truth a whole team and its agents read from, which keeps sessions shorter and keeps them agreeing with each other.

At a Glance

Overview

An agent is only as useful as the actions it can take. LangChain's tools documentation describes tools as the way agents fetch real-time data, execute code, query external databases and take actions in external systems. This skill is about turning an API client, a database query or a helper function into one of those tools: a named, described, schema-bound capability the model can choose to call, with a predictable result coming back whether the call succeeds or fails. For background on the framework itself, see the LangChain method page.

The inputs to the work are concrete. You need the operation you want to expose (an endpoint, a SQL query, a calculation), the arguments it takes and their types, the clients and credentials it depends on, and a clear idea of what the model should see when it finishes. The output is a tool definition, usually a Python function wrapped with the @tool decorator, which the tools guide presents as the simplest custom-tool pattern, plus a policy for what happens when that function fails.

Most LangChain integrations questions come down to the boundary between prompt and tool. Instead of describing every operation inside the system prompt and hoping the model formats requests correctly, you expose explicit, well-described capabilities the model can select. The description tells the model when the tool applies, the schema tells it which arguments are legal, and the return value becomes an observation the agent reasons over on its next step.

The integration surface keeps widening, which makes clean tool boundaries more valuable, not less. Cloudflare's Python Workers now run openai, langchain and mcp natively, and Cloudflare ships a langchain-cloudflare package for pointing chains at its own inference. LangChain has also integrated TypeSafe's Jev model through a TypeSafeClassifier that returns typed, confidence-bearing decisions for routing and control. Each of these is another capability competing for the model's attention, and a vague description or loose schema is how an agent ends up calling the wrong one.

You will know the skill is working when the agent picks the right tool from its description alone, passes arguments that validate on the first try, and recovers gracefully when an upstream API times out instead of crashing the run or inventing an answer.

How It Works

Every tool call follows the same contract. The model reads the available tool names, descriptions and argument schemas, decides a tool is needed, and emits a tool call whose arguments must match that schema. The tool runs and returns either an observation or an error, and the agent incorporates that result into its next decision. LangChain's tools guide frames tool execution around exactly this exchange, and the older ReAct agent prompt in langchain-classic makes it visible: the model gets an input question and an agent scratchpad where intermediate reasoning and prior tool use are written out.

In the current architecture that scratchpad lives in the message history. The agent documentation describes a loop in which the model repeatedly chooses whether to respond or call a tool, and tool results are fed back into the messages so the model can keep reasoning from what came back. That has two consequences for integration design. First, whatever your tool returns is read by the model, so a bloated JSON dump costs context and attention on every later step. Second, an error is also just a message, which means you can design errors the model can act on.

Three parts of a tool determine whether the model uses it well:

• Name. A short, verb-first name such as search_orders or create_ticket tells the model what kind of action it is.
• Description. This is the model's only guide to when the tool applies. It should state the purpose, when to use it, when not to, and what comes back.
• Argument schema. Typed parameters with clear names constrain what the model can send. The tighter the schema, the fewer malformed calls reach your API.

Typed contracts are becoming the norm across integrations. LangChain's Jev integration, for example, lets an application submit its current state and a set of typed questions through .invoke() and get typed decisions back. The same principle applies to your own tools: typed in, predictable out.

Failure handling sits outside the tool function. LangChain configures tool execution and tool-error handling through its middleware system, which lets you decide centrally whether a failed call is retried, converted into an error message the model can read, or surfaced to a human. Keeping that policy in middleware rather than scattering try/except blocks across tools means every tool fails the same way, and you can change the policy without touching integration code.

The practical result is a clean split of responsibilities. The tool function does one operation and returns a compact result. The description and schema govern selection and argument quality. Middleware governs what happens when things break. For how tools fit into the wider agent design, see Designing Autonomous Agents.

Step-by-Step Guide

Step 1: Choose the operations to expose

List the actions the agent genuinely needs to complete its job, such as looking up an order, running a report query or creating a ticket. Expose each as a separate, narrowly scoped tool rather than one generic call_api function with a free-form payload. Narrow tools are easier for the model to choose between and easier for you to secure. Decide for each whether it only reads data or changes something in an external system, because write actions need stricter validation and possibly human approval.

Pro tip: If you cannot describe the tool's purpose in one sentence, split it into two tools.

Step 2: Write a typed function for each operation

Implement each operation as a plain Python function with explicit, typed parameters and descriptive argument names. Keep clients, credentials and base URLs out of the argument list so the model never has to supply them. Test the function directly, without an agent, against the real or sandboxed API. This isolates integration bugs from model behavior, which saves hours of confused debugging later.

Pro tip: Prefer enumerated or constrained types (a status from a fixed set) over open strings wherever the API allows it.

Step 3: Wrap it with @tool and write the description

Apply LangChain's @tool decorator, the simplest custom-tool pattern in Python, to turn the function into a tool the agent can bind. Give it a verb-first name and a description that states what it does, when to use it, when not to use it and what it returns. Write the description for the model, not for a colleague: be explicit about units, formats and required identifiers. When two tools could plausibly apply to the same request, say in each description how to tell them apart.

Pro tip: Read only the names and descriptions of all your tools side by side and check that a stranger could pick the right one for a sample request.

Step 4: Shape the return value as an observation

Decide exactly what the model should see after the call succeeds. Strip raw API responses down to the fields the agent needs to answer or take the next step, and use consistent keys across tools. Include identifiers the agent may need for follow-up calls, such as an order ID it could pass to a refund tool. Avoid returning huge payloads, because every tool result is appended to the message history and read again on later turns.

Pro tip: For list results, return a capped number of items plus a count, and let the agent ask for more if needed.

Step 5: Configure error handling in middleware

Define how failed tool calls behave using LangChain's middleware, where tool execution and error handling are configured. Distinguish recoverable errors (timeouts, rate limits, invalid arguments) from fatal ones (authentication failures, forbidden actions). For recoverable errors, return a short message the model can act on, such as which argument was invalid and what format is expected. For fatal or risky errors, stop the run or route to a human rather than letting the model retry indefinitely.

Pro tip: Error messages should tell the model what to do next, not just what went wrong.

Step 6: Register the tools and test selection

Pass the tool list to your agent and run a set of representative requests, including ones that should use no tool at all. Check which tool was chosen, whether the arguments validated on the first attempt and whether the final answer used the observation correctly. Force failures by pointing a tool at a broken endpoint and confirm the agent recovers as your middleware policy intends. Treat misrouted calls as description bugs first and fix the wording before adding more prompt instructions.

Best Practices

• Keep one operation per tool. A tool that does exactly one thing has a clear description and a tight schema, which is what lets the model choose it reliably and lets you reason about its permissions.
• Put the selection logic in the description, not the system prompt. Descriptions travel with the tool wherever it is reused, while prompt instructions about tools drift out of sync as the tool set changes.
• Keep secrets and configuration out of tool arguments. Inject clients and credentials when you build the tool so the model can neither see nor alter them, and so a prompt injection cannot redirect a call to another account.
• Return compact, consistent observations. Because tool results are fed back into the message history, a lean return shape saves context on every later step and makes it easier for the model to pick out the fields that matter.
• Centralize failure policy in middleware. LangChain handles tool execution and errors through middleware, so one policy for retries, error messages and escalation keeps every tool behaving the same when an upstream service breaks.
• Gate write actions more strictly than reads. Validate arguments server-side even when the schema already constrains them, and consider requiring confirmation for irreversible actions such as payments or deletions.

Common Mistakes

• Describing operations in the prompt instead of exposing them as tools. The model has to invent request formats, and nothing validates what it produces.: Expose each operation as an explicit, well-described capability with a typed schema, so the model selects it and the schema constrains its arguments.
• Shipping tools without failure handling. A single timeout or malformed argument crashes the run or, worse, the model invents a result it never received.: Configure tool-error handling in LangChain's middleware so failures return a readable error the agent can recover from, or stop the run when retrying is unsafe.
• Writing vague, overlapping descriptions such as "gets data" for several tools. The agent calls the wrong tool or alternates between them.: State purpose, when to use, when not to use and return shape in every description, and name the distinguishing condition when two tools are similar.
• Returning raw API responses verbatim. Large payloads crowd the context window and bury the fields the model actually needs.: Map responses to a small, consistent set of fields and cap list lengths before returning them as the observation.
• Treating the tool contract as loose text. Without typed inputs and predictable outputs, downstream decisions become guesswork, which is the opposite of how typed integrations such as LangChain's TypeSafeClassifier are designed.: Use typed parameters and a fixed return shape for every tool, and validate both in tests before the tool reaches an agent.

References

• Examples: Worked examples and scenarios
• FAQ: Frequently asked questions
• Parent Method: LangChain

Related Skills

• Designing Autonomous Agents with LangChain
• Building RAG Pipelines with LangChain
• Managing Memory and Conversation State in LangChain
• Chaining Prompts and Composing LLM Workflows
• Configuring LLM Providers and Models in LangChain
• Loading and Splitting Documents for LLM Processing
• Crafting Reusable Prompt Templates in LangChain

Sources

• Cloudflare Ships Python Workers GA With FastAPI, MCP
• LangChain adds TypeSafe's Jev to the agent control loop
• tools
• create_react_agent | langchain_classic - LangChain Reference
• Configure the harness

Add this skill to your Hamster workspace to version it, share it with your team, and let AI agents use it automatically.