Production failures

n8n ai agent not calling tools

Workflow · n8n-agent-tool-calling-repro.json · updated 2026-08-06

An n8n AI Agent that answers your question but never touches the tool you gave it is almost never an n8n bug. In the large majority of reports it is the model underneath the Agent failing to emit a structured tool call, and n8n faithfully showing you the text it got back. The fix is usually one dropdown, not a workflow rewrite. This page separates the one cause that is really about n8n from the several that are about the model, because chasing the wrong one is how people lose an afternoon.

The symptom

The Agent runs, returns a plausible answer, and the tool sub-node underneath it shows no execution at all. No error, no red node, just a tool that was never called. In the clearest version of the failure the Agent's output is not prose but a JSON object with the tool call spelled out as text. One reported case, using Gemini 2.5 Pro through n8n, returned a body containing "functionCall": { "name": "Airtable_Send", "args": { ... } } verbatim, with every argument correct, and still did not run the Airtable node. The model described the call it wanted to make instead of making it, and n8n printed the description.

A second shape looks like the Agent trying and giving up. Instead of a silent skip you get the error Max iterations (10) reached. The agent could not complete the task within the allowed number of iterations. The Agent looped, never produced a call the runtime could act on, and hit its ceiling. Same underlying problem, louder failure mode.

A third shape is intermittent. The same workflow calls the tool on one run and ignores it on the next with no change on your side. Two different things produce this and they need different responses: a model or provider version that moved under you, or plain sampling nondeterminism on a borderline prompt, where the model was always going to skip the call some fraction of the time. It is the version of this bug that wastes the most time, because it looks like your prompt.

What causes it

The model does not do structured tool calling. This is the dominant cause by a wide margin. The n8n Tools Agent implements LangChain's tool-calling interface, which means it depends on the model returning a machine-readable tool call, not a sentence about one. Models that are weak at this, or that route through a provider that does not expose the function-calling API, emit the call as text and the Agent has nothing to execute. Gemini is the name that recurs most in reports, and small self-hosted models are close behind: one user found nvidia/llama-3.1-nemotron-nano-4b returned tool calls as plain strings while the same workflow worked on a larger model. The tool, the prompt and the wiring were all fine. The model was the variable.

A workflow migrated from an older agent type. Earlier n8n exposed several agent types (Conversational, ReAct, Plan and Execute, OpenAI Functions) that parsed the tool call out of the model's plain text. Recent versions collapsed the Agent node onto the Tools Agent and, in some releases, dropped the agent-type selector altogether, which is why users report the type field simply gone. A weak model that limped along under ReAct, because n8n was doing the parsing, has nothing to lean on under the Tools Agent, which hands the call to the provider's function-calling API. If the same graph worked before an upgrade and stopped after, this is a prime suspect.

The tool's parameters are misconfigured. A tool can be effectively ignored even when the model does call it, if its arguments never arrive. n8n fills tool parameters through the $fromAI() expression, and there are real gaps: arguments from the model's tool call have been reported not reaching n8n-native tool nodes as $json while the same setup worked for built-in LangChain tools. A tool that is called but receives empty or wrong arguments looks, from the chat, exactly like a tool that was never called, which is why this one hides so well.

A connected tool is deactivated in place. This one genuinely is an n8n behaviour. If you connect two or more tools to an Agent and disable one by selecting it and pressing D, some versions fail every request that needs any tool, ending in the Max iterations (10) reached error rather than quietly ignoring the disabled node. It was reported on n8n 2.9.4 and closed as could-not-reproduce, which tells you it is environment- and version-dependent, not universal. It is worth knowing precisely because it looks identical to a model problem from the outside.

The instruction does not make the tool worth calling. A model decides to call a tool from the tool's name and description and from your system prompt. If the description is empty or generic, or the prompt never tells the model the tool exists and when to use it, a capable model will often just answer from its own knowledge. This is real, but it is over-prescribed as the cause: people rewrite prompts for a week when the model was incapable of a structured call in the first place.

A version or provider regression. Several reports describe workflows that called tools reliably for months and then stopped after an update, with threads titled along the lines of tools not working since yesterday and an agent that stopped using its assigned tools. When the graph did not change and the behaviour did, suspect the model version, the n8n release, or the provider before you suspect your own configuration.

Telling it apart

Before you change anything, answer one question: did the model even attempt a structured call? Everything downstream depends on it, and n8n shows you the answer if you look in the right place.

Open the Agent's execution and read the raw model output, not the final Agent answer. If the output contains a functionCall or tool_calls structure rendered as text, the model tried and its call never became a real invocation. That is a capability or provider problem, and no amount of prompt work will fix it. If the output is ordinary prose with no attempt at a call, the model chose not to call the tool, which points at the prompt and the tool description. If the run ends in Max iterations (10) reached, check whether any connected tool is deactivated before assuming anything about the model.

The decisive test is to hold everything constant except the model. Run the same graph, same prompt, same tool, and change only the model. If the tool executes on one model and is ignored on another, the model was the cause and you are done. This is exactly what the artifact on this page is built to do: a Tools Agent, one Calculator tool, and a prompt that can only be answered correctly by calling it. Swap the model and watch the Calculator sub-node either execute or stay untouched.

The fix

The order is deliberate, cheapest and most common first.

1. Use a model that reliably emits tool calls. On the current provider list that means OpenAI, Anthropic, Groq, Mistral or Azure OpenAI models known for function calling. In practice teams settle on a strong Anthropic or OpenAI model for anything with more than one tool. If you must run a small or self-hosted model, verify tool calling in isolation before you build a graph on top of it, because most small models degrade on exactly this capability first.
2. Delete tools you are not using, do not deactivate them. If you want a tool off the Agent, remove the connection rather than disabling it in place. On the versions where the deactivated-tool bug bites, that one configuration turns a working Agent into a loop that dies at the iteration ceiling, and deleting sidesteps it whatever your version.
3. Confirm the tool receives its arguments. Check that each $fromAI() parameter is mapped and that the tool node sees non-empty input on a run. A tool called with empty arguments fails as quietly as one never called, so a green node is not proof on its own.
4. Make the tool worth calling. Give every tool a name and a one-line description that says what it does and when to use it, and name the tool in the system prompt. Do not stop at the prompt though: an explicit instruction cannot rescue a model that cannot make a structured call.
5. Pin your versions. Once a graph works, record the model id and the n8n version. When it breaks with no change on your side, the first diagnostic is which of those two moved.
6. If tool calling stays unreliable, drop the Agent for that step. For a single, deterministic action, a plain LLM node followed by the node you would have called as a tool is more reliable and cheaper, because it removes the model's discretion entirely. Reserve the Agent for genuinely open-ended routing. The same instinct that bounds a runaway loop in LangGraph applies here: take the decision away from the model when the decision is not really open.

Verifying the fix

Prove the tool executes, do not trust the final answer. A correct final number is not proof the tool ran, because a capable model can compute a small result itself. Open the tool sub-node in the execution and confirm it has an input and an output for the run. If it does not, the Agent answered without it.

Force a call the model cannot fake. The artifact uses 23951 * 417, forbids the model from computing it, and expects 9987567 from the Calculator. Run it once with a model known to be weak at tool calling and once with a strong one, changing nothing else. The weak model leaves the Calculator untouched or returns a functionCall blob; the strong model executes the Calculator. That contrast, on your own instance, is the whole diagnosis in two runs.

Then watch it under real load for a few days. Tool-calling reliability is not binary across inputs. A model that calls the tool on clean prompts can skip it on messier ones. Log, per run, whether the expected tool executed, and treat a rising skip rate as a model change to investigate, not a prompt to tweak. If you are wiring agents into production and want this measured rather than guessed, that is the kind of work we do in agentic systems, and the n8n pillar covers where the Agent node fits and where it does not.

Sources

Every claim here traces to either the reproduction workflow on this page or a reported case in the page's sources field. The functionCall emitted as text, with the Airtable example and the move to a stronger model as the resolution, is from the n8n community thread on the Agent not calling a tool. The deactivated-tool failure with the Max iterations (10) reached error, on n8n 2.9.4 and closed as could-not-reproduce, is GitHub issue 26356. The dependence on the model's tool-calling capability follows from the Tools Agent documentation, which states the node implements LangChain's tool-calling interface. The small-model case is the NVIDIA developer-forum thread on the nemotron model returning tool calls as strings. The tool-parameter gap, where a native tool node does not receive the model's arguments while a built-in LangChain tool does, is GitHub issue 15506, and the $fromAI() mechanism it depends on is the n8n documentation on letting the model specify tool parameters. The move to the Tools Agent and the disappearing agent-type selector are the self-hosted 1.82.2 report. The regression reports, the tool-description and required-instruction cases, and the general shape of the failure are drawn from the remaining community threads listed in the sources.