My LangChain agent keeps failing tool calls, how do I fix it?

Tool-call failures in LangChain agents usually come from one of a few buckets: tool schema mismatch, model/tool support mismatch, bad tool outputs, or agent prompting/execution issues. Here’s a practical checklist to fix them.

1) Make sure the model actually supports tool calling

Not every chat model supports structured tool/function calling the same way.

• Use a model that supports tool use reliably.
• Check whether you’re using:
  • legacy function calling
  • modern tool calling
  • JSON output parsing
• If you’re on an older model/provider, tool calls may be flaky or unsupported.

2) Verify the tool signature matches what the model expects

A very common issue is a mismatch between the tool’s Python signature and the schema LangChain generated.

Example of a clean tool:

from langchain_core.tools import tool

@tool
def get_weather(city: str) -> str:
    """Get the weather for a city."""
    return f"It's sunny in {city}"

Common problems:

• Missing docstring/description
• Weird parameter types the model can’t serialize
• Required fields not clearly named
• Complex nested objects when a simpler schema would do

If you need structured inputs, define a schema explicitly with Pydantic.

3) Ensure your tool returns a string or JSON-serializable output

Agents often fail because the tool returns something the model/runtime can’t handle.

Good:

return {"city": city, "temp": 72}

Better:

import json
return json.dumps({"city": city, "temp": 72})

Avoid returning:

• raw objects
• database cursors
• custom classes
• open file handles
• numpy/pandas objects unless serialized first

4) Check that the tool name is stable and simple

Tool names should be:

• short
• lowercase-ish
• alphanumeric/underscore
• not duplicated

Bad:

• "Get Weather!!!"
• duplicate tool names
• names changing dynamically

Good:

• "get_weather"

5) Inspect the exact error message

The fix depends heavily on the failure mode. Common ones:

“Tool input validation error”

The model passed wrong/missing arguments. Fix by:

• simplifying the schema
• making arguments optional where possible
• improving tool descriptions
• adding examples in the prompt

“Invalid tool call” / malformed JSON

The model didn’t produce valid structured output. Fix by:

• using a stronger tool-capable model
• setting temperature to 0
• tightening the prompt
• using a parser/retry mechanism

“Tool execution error”

Your Python tool crashed. Fix by:

• wrapping the tool in try/except
• logging inputs
• validating args before use

6) Add robust error handling around tools

Example:

from langchain_core.tools import tool

@tool
def get_weather(city: str) -> str:
    """Get the weather for a city."""
    try:
        if not city:
            raise ValueError("city is required")
        return f"It's sunny in {city}"
    except Exception as e:
        return f"Tool error: {str(e)}"

For production, you may want to raise errors instead of swallowing them, but while debugging this helps identify the problem.

7) Simplify your agent setup

If you’re using a complex agent chain, reduce it to the smallest working example.

Try:

• one model
• one tool
• one simple prompt
• one input

Then confirm:

1. the agent chooses the tool
2. the tool receives correct args
3. the tool result is returned to the model

8) Make the prompt explicitly mention tool usage

The agent may not be choosing tools because the instructions are vague.

Example:

Use the available tools whenever the user asks for weather data. Do not guess.

For tools with required parameters, be explicit:

When calling get_weather, always provide the city as a plain string.

9) Use LangChain’s agent/tooling APIs consistently

Mixing old and new APIs can cause subtle issues.

For newer LangChain versions, prefer:

• langchain_core.tools.tool
• modern chat models with tool calling
• the current agent constructors/helpers for your version

If you’re using deprecated agent classes, consider upgrading.

10) Turn on verbose logging

This is one of the fastest ways to see where it breaks.

agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

Also log:

• model input messages
• tool schemas
• raw tool call arguments
• tool outputs

11) Common fixes by symptom

Tool never gets called

• model may not support tools
• prompt doesn’t encourage tool use
• agent type doesn’t match model
• tool descriptions are weak

Tool gets called with wrong args

• simplify schema
• make descriptions more concrete
• reduce argument count
• set temperature to 0

Tool gets called, but agent fails afterward

• tool output format is not usable
• output is too large
• output isn’t serializable
• model can’t interpret the result

Works sometimes, fails sometimes

• nondeterministic model output
• tool schema too complex
• prompt ambiguity
• rate limits or transient provider issues

12) Minimal working example

Here’s a simple pattern to test:

from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langchain.agents import initialize_agent, AgentType
from langchain.agents import AgentExecutor

@tool
def add(a: int, b: int) -> str:
    """Add two numbers."""
    return str(a + b)

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
tools = [add]

agent = initialize_agent(
    tools,
    llm,
    agent=AgentType.OPENAI_FUNCTIONS,
    verbose=True
)

result = agent.invoke({"input": "What is 2 plus 3?"})
print(result)

If this works, the issue is likely in your original tool schema, prompt, or chain composition.

---

If you want, paste:

1. your tool definition
2. the agent setup code
3. the exact error message / stack trace

and I can tell you the specific fix.