Fix n8n AI Agent Calling the Wrong Tool

When an n8n AI agent calls the wrong tool, the cause is almost never the wiring. The model never sees your canvas. At selection time it sees a flat list of tool names, descriptions and input schemas, and it picks whichever one reads closest to the job it thinks it has. If two of your tools could plausibly be described by the same sentence, the agent will eventually pick the wrong one — and no amount of re-connecting nodes changes that. There are four causes we run into on client builds, and three of them are fixed by editing text rather than logic. The fourth one is invisible on the canvas entirely, which is why it wastes the most time.

What the agent actually sees when it chooses

The Tools Agent turns every connected tool sub-node into a function definition: a name derived from the node name, the description you typed, and a JSON schema of the inputs. That package goes to the model with every request. The canvas, the node colors, the order you dragged things in, the sticky note you wrote explaining the design — none of it goes.

So when you have Get Customer and Get Customer Orders and Search CRM attached to the same agent, and all three descriptions start with "Retrieves customer data from the CRM," you have not given the model three tools. You have given it one tool three times and asked it to guess. It will be right most of the time, and wrong often enough to break a client's workflow at 2am.

This is also why the failure looks intermittent. Nothing is broken. The model is sampling, and when two options score close together, the choice flips run to run. An intermittent wrong-tool bug is a tie in the descriptions, not a race condition in n8n.

Cause 1: The agent is holding a stale copy of your sub-workflow schema

This is the one that costs a full afternoon, because every visible signal says the setup is correct.

The Call n8n Workflow Tool stores the sub-workflow's input schema inside the parent agent's configuration, separately from the visual connection on the canvas. Edit the sub-workflow's Execute Workflow Trigger inputs — add a field, rename one, change a type — and the parent does not automatically pick that up. The line on the canvas still looks connected because it is. The schema behind it is out of date.

What you see next is strange and specific: the agent either behaves as if that tool does not exist and reaches for a different one, or it calls the right tool with the wrong parameter shape and you get schema mismatch errors. Both symptoms point you at the model. Neither has anything to do with the model.

The fix takes ten seconds. Disconnect the tool from the agent, save, reconnect it, save again. If that does not clear it, delete the tool node and re-add it. Then make it a habit: every time you change a sub-workflow's inputs, open and re-save every parent workflow that calls it. On a multi-tenant setup where one sub-workflow serves a dozen agents, that habit is the difference between a clean deploy and a week of phantom bugs. We cover the architectural side of that split in AI Agent node vs sub-workflow.

Check this first. It is cheap to rule out, and if you skip it you will spend hours rewriting descriptions that were fine.

Cause 2: Your descriptions say what the tool is, not when to use it

Most tool descriptions are written like documentation. The model does not need documentation. It needs a decision rule.

Here is the shape that keeps failing:

• "Fetches contact records from HubSpot." Fine as a label. Useless next to three other HubSpot tools.
• "Search the CRM." Search for what? Compared to which alternative?
• "Updates the deal." Which deal, under what condition, and what happens if there is no deal yet?

And here is the shape that works. Every description answers three questions in order: when to reach for this, when not to, and what it returns.

• "Look up ONE contact by email address when you already have the email. Returns the contact record with lifecycle stage and owner. Do not use this to find contacts by company or name — use Search Contacts for that."
• "Search for contacts by company name or partial name when you do NOT have an email address. Returns up to 10 matches with emails. If you already have an exact email, use Get Contact By Email instead — it is faster and exact."

The pattern is that each description names the sibling it gets confused with and draws the line. That single move fixes the majority of wrong-tool bugs we get handed, and it costs nothing at runtime.

Two supporting habits matter as much. Name nodes for the decision, not the integration — Get Contact By Email beats HubSpot1 by a mile, and n8n derives the function name straight from the node name. And write descriptions in the imperative, addressed to the agent. "Use this when…" reads as an instruction. "This node is responsible for…" reads as prose the model has to interpret.

The official n8n guidance on tools makes the same point in fewer words: the description is the interface.

Cause 3: You attached too many tools to one agent

There is a point where no amount of careful writing saves you, because the descriptions have nowhere left to go. Every tool you add has to be distinguishable from every tool already attached, and that gets harder faster than it feels like it should.

After building and maintaining 200+ production n8n workflows, our working rule is five tools maximum on a single agent, and two or three if the agent runs on a small self-hosted model with a tight context window. Past five, two things happen at once. Descriptions start overlapping because the tools genuinely do overlap. And every tool definition consumes context that the agent needs for the conversation, the memory and the actual reasoning.

The overload symptom is distinct from the ambiguity symptom. Ambiguity gives you a confident wrong call. Overload gives you an agent that calls three tools in a row hunting for the right one, then burns through its iteration budget. If you are hitting the default ceiling of 10 iterations, read why raising max iterations is the wrong fix — the cause is usually sitting in this section.

The fix is not a bigger model. It is a second agent. Split by job, not by integration: one agent that reads and reports, one that writes and updates. Each gets three or four tools it can never confuse, and a router or a simple branch sends work to the right one. Smaller agents are also far easier to test, which matters when a client is watching.

Cause 4: The model fills your parameters and you never told it how

Tool selection and tool arguments fail independently, and the second one is easy to misdiagnose as the first. The agent picks the correct tool, sends garbage into it, the call errors, and in the execution log it looks like the tool was simply wrong.

Any parameter you let the model fill is a parameter you have to describe. Not the field name — the field name is not a spec. State the format, the allowed values, and where the value is supposed to come from:

• Bad: a status field with no description. The model sends Complete, done, COMPLETED and finished across four runs, and your API rejects three of them.
• Good: "Deal stage. Must be exactly one of: new, qualified, proposal, closed_won, closed_lost. Lowercase, underscores, no other values accepted."
• Bad: a date field with no description. You get next Tuesday.
• Good: "Appointment start time in ISO 8601 with timezone offset, for example 2026-09-21T14:30:00-05:00. Use the customer's local timezone from the contact record, never the server timezone."

Then validate on the receiving end and return an error the agent can actually use. Error: invalid input teaches it nothing and it retries the same mistake. Error: status must be one of new, qualified, proposal, closed_won, closed_lost — received "Complete" gets corrected on the next call, usually the first try. That one change turns a dead-end failure into a self-healing one.

The ten-minute diagnostic

Work in this order. It is sorted by cost, not by how likely each cause feels.

1. Open the failed execution and read the agent's intermediate steps. Write down the tool it called and the exact arguments. Wrong tool is a description problem. Right tool, wrong arguments is a parameter problem. Do not guess which one you have.
2. Bounce every sub-workflow tool. Disconnect, save, reconnect, save. Thirty seconds, and it rules out the stale schema that no other check will surface.
3. Count the tools. Six or more, stop diagnosing and split the agent. You will not fix overload with wording.
4. Read your descriptions as if you were the model. Cover the node names and ask whether you could pick correctly from the descriptions alone. If you cannot, the agent cannot.
5. Check every model-filled parameter has a description with format and allowed values. Undescribed fields are guesses.

Then re-run the same input ten times, not once. Tool selection is probabilistic, and a single green run proves nothing — we go through the full regimen in how to test n8n AI agents before production.

Catch the next one before the client does

The uncomfortable part of wrong-tool bugs is that they do not throw. The agent picks a plausible tool, gets a plausible result, and returns a confident answer built on the wrong data. Nothing goes red. Nobody files a ticket. You find out when a client asks why a deal moved stages on its own.

That is why we log every tool call — name, arguments, latency, result — on any agent that touches a client system, and alert on tools that get called far more or far less than expected. A tool that was invoked 40 times last week and zero times this week is telling you something changed, usually a schema. Agent observability in n8n covers the setup.

Fix the descriptions, cap the tool count at five, describe every parameter, and re-save parents when sub-workflow inputs change. Four habits, and the category of bug mostly stops happening.

If you have an agent misbehaving in production and you would rather not spend the afternoon on it, get a free automation audit. We will review your agent setup, tool descriptions and execution logs and tell you exactly which of these four is biting you — no charge, no pitch required.