# Green Node, Failed Tool: An n8n Guard for Agent Tool Calls

> A free n8n workflow that checks agent tool calls for four failure signals, sends temporary ones to a retry placeholder you wire, and stops the run on the rest.

- Source: https://www.zarifautomates.com/blog/n8n-tool-call-guard-workflow
- Published: 2026-11-18
- Pillar: Automation Workflows
- Tags: n8n workflow, ai agents, agent reliability, error handling, free download
- Author: Zarif

---

To catch an AI agent tool call that failed while n8n shows a successful run, check what each tool returned, not whether its node finished. The free workflow below does that for every tool call. It flags an empty result, an error field in the body, a non-2xx status code, or missing required fields. Failures that look temporary go to a retry placeholder, which you replace with the node that repeats the call. Every other failure ends the run at a Stop and Error node, so the run turns red and an error workflow can alert someone.

One caveat before you download it. The retry placeholder does nothing until you replace it. So a run whose only failures are retryable, such as a 429 or a 503 on a call's first attempt, finishes green with nothing retried and no alert. Wire the retry before you rely on the guard.

[Download the tool call guard workflow (n8n JSON, v1)](/downloads/n8n-tool-call-guard-v1.json). It's free, with no signup. It uses only core n8n nodes, holds no credentials and has no model node, so it needs no API key. It imports inactive.

What was tested: the JavaScript inside the workflow's Code nodes runs in this site's test suite against nine made-up tool calls, and a test checks the file's structure. As of November 18, 2026 the workflow hasn't been imported into a live n8n instance for this guide. Treat your first import as part of your own test, and if a count below doesn't match, trust what your n8n shows.

## Why a green node can hide a failed tool call

n8n marks a node as succeeded when it finishes without throwing an error. A tool call can finish cleanly and still have failed:

- An API answers with status 200 and a body like `{"success": false, "error": "subject is required"}`.
- An HTTP Request node is set to keep going on errors, so a 404 comes back as data instead of stopping the run.
- A lookup returns an empty list or `{}` because the record wasn't found.
- A tool returns something, but not the fields the next step needs.

An agent adds one more layer. The model reads the tool's output as text and writes its answer from it, and nothing forces that answer to agree with the tool. The sample run includes a made-up agent reply, "I created the ticket for you.", sitting next to a ticket call that came back with a rate-limit error.

So the run's color tells you the workflow ran. It doesn't tell you the tools worked. The guard checks the second thing.

## What the guard checks

The **Check tool result** node looks for four signals in each tool call:

| Signal | Flagged when | Sample that triggers it |
| --- | --- | --- |
| `non_2xx_status` | A status code is present and outside 200 to 299 | `lookup_order` returns 404 |
| `error_field` | The body has a truthy `error` or `errors`, or `success` or `ok` set to false. A text result that starts with "error" also counts | `create_ticket` returns 200 with `success: false` |
| `empty_result` | The result is missing, an empty string, an empty list or an empty object | `lookup_order` returns `{}` |
| `schema_mismatch` | A field you listed as required is missing or null | `lookup_order` returns `id` and `state` instead of `order_id` and `status` |

The schema check only runs when nothing else fired, so one broken call doesn't produce four overlapping complaints.

Then each call gets a route. No signal means `pass`. A status of 408, 429, 500, 502, 503 or 504 on a call that hasn't used up its attempts means `retry`. Everything else means `alert`.

## Import it and run the samples

In the n8n editor, create a new workflow, open its menu, choose **Import from File** and pick the downloaded JSON. n8n's [import guide](https://docs.n8n.io/build/manage-workflows/export-and-import) covers the options. Then select **Execute workflow**.

The sample node holds nine tool calls: seven sent on their own and two taken from one agent run. Running the Code nodes' JavaScript on them gives these counts, so this is what the canvas should show:

| Node | Items |
| --- | --- |
| Split out tool calls | 9 |
| Tool call passed? | 2 true, 7 false |
| Worth a retry? | 2 true, 5 false |
| Build alert message | 1 |

The run then stops at **Fail the run**, in red, on purpose. Its error message lists the five calls that failed for good:

```text
5 tool call(s) failed behind a successful-looking run:
- lookup_order, attempt 1: empty_result
- create_ticket, attempt 1: error_field: error, success is false
- lookup_order, attempt 1: non_2xx_status: 404
- lookup_order, attempt 1: schema_mismatch: missing order_id, status
- search_docs, attempt 2: non_2xx_status: 503; empty_result
```

The retry branch pauses five seconds in **Wait before retry** before the run reaches the alert branch, so the red result takes a moment to appear.

## Walk through the workflow node by node

### The two ways in

**Run with sample tool calls** is a Manual Trigger, and **Sample tool calls** is a Code node that returns the nine made-up calls. Nothing in it touches a real tool. Keep both for testing.

**When called by another workflow** is an Execute Workflow Trigger set to accept all data. Your agent workflow calls the guard through it. Real tool calls enter here and skip the samples. The [Execute Workflow Trigger docs](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.executeworkflowtrigger/) cover its input options.

### Split the agent run into tool calls

**Split out tool calls** turns its input into one item per tool call. It accepts two shapes.

The first is an AI Agent node's output with intermediate steps included. The [AI Agent node docs](https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/) list a Return Intermediate Steps option that adds the steps the agent took to its output. The node reads each step's `action.tool` as the tool name and its `observation` as the result. Before you rely on it, open your agent's output panel once and check those field names match. If they don't, change them in this node.

The second shape is a single tool result you send yourself: `tool`, `statusCode`, `attempt` and `result`. Use it for tools outside an agent, such as an HTTP Request node. The [HTTP Request docs](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/) describe a response option that includes the headers and status code, which is where `statusCode` comes from.

Results that arrive as JSON text are parsed, including a JSON-encoded string, so an observation of two quote characters counts as empty. Anything else stays as text.

### Check every result

**Check tool result** applies the four checks above. It has three settings at the top, each marked `EDIT`:

- `REQUIRED_FIELDS` lists the fields each tool must return. The samples use `lookup_order` and `create_ticket`. Replace them with your tools. A tool you don't list skips the schema check, so add every tool whose output feeds another step.
- `MAX_ATTEMPTS` is how many times one call may run before a temporary failure becomes an alert. It's set to 2.
- `RETRYABLE_STATUS` lists the status codes worth retrying.

Each item leaves with a `guard` object: `passed`, `retry`, `route`, the `signals` it found, the `attempt` number and `nextAttempt` for retries. The node never drops a failure. It labels it and passes it on.

### Route each call: pass, retry or alert

**Tool call passed?** is an If node on `guard.passed`. Its true branch goes to **Passed: continue here**, a No Operation node. Connect whatever should happen with a good result there.

Its false branch goes to **Worth a retry?**, a second If node on `guard.retry`.

Retries go to **Wait before retry**, a Wait node set to five seconds, then to **PLACEHOLDER: call the tool again**. That placeholder does nothing. Replace it with the node that repeats the call, and send the new result back into the guard with `attempt` set to `guard.nextAttempt`. The [Wait docs](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.wait/) cover the interval settings.

Alerts go to **Build alert message**, a Code node that gathers every failed call into one message, then to **Fail the run**, a [Stop and Error](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.stopanderror/) node. It fails the execution with that message, and that failure is what turns the run red.

The alert branch sits lowest on the canvas on purpose. The workflow uses n8n's v1 execution order, which, per the [execution order docs](https://docs.n8n.io/flow-logic/execution-order/), runs branches from top to bottom. So the pass and retry branches finish before Stop and Error ends the run.

### Turn the red run into an alert

**When a run fails** is an [Error Trigger](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.errortrigger/). It starts this part of the workflow when a workflow that uses this one as its error workflow fails. **Describe the failed run** turns the failure into one line of text with the workflow name, the node where it stopped and the error message. **PLACEHOLDER: send the alert** is where your Slack, email or HTTP Request node goes. Send it the `text` field.

The Error Trigger docs say it doesn't fire when you run a workflow by hand, so the sample run stops at **Fail the run** without reaching this branch. That's expected.

## Connect it to your agent workflow

1. On your AI Agent node, turn on Return Intermediate Steps.
2. After the agent, add an Execute Workflow node (newer n8n versions call it Execute Sub-workflow) and point it at the guard.
3. In **Check tool result**, replace the sample entries in `REQUIRED_FIELDS` with your tools and their required fields.
4. In your agent workflow's settings, set the error workflow to the guard. n8n's [error handling guide](https://docs.n8n.io/flow-logic/error-handling) explains error workflows.
5. Publish the guard. Per the usage notes in the [Error Trigger docs](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.errortrigger/), the workflow that holds the Error Trigger must be published for it to fire.
6. Replace both placeholders. Until the retry placeholder repeats the call, temporary failures are dropped without an alert.
7. Run the agent on a case where you know a tool fails, and confirm the alert arrives. The same docs say error workflows can't be tested through manual runs, so trigger the agent workflow the way it runs in production rather than with **Execute workflow**.

Step 7 matters most. A guard you've never seen fail isn't tested yet.

## What the guard won't catch

**A well-formed wrong answer.** If a lookup returns the wrong order with every field present, all four checks pass. Catching that takes reviewed reference answers, which is what the [agent evaluation lesson](/blog/evaluate-ai-agent-performance-reliability) builds.

**A call that shouldn't have run.** The guard checks results after the fact. If an action needs a person's yes before it happens, use a stored approval like the one in the [human approval lesson](/blog/how-to-build-ai-agent-human-in-loop-approval).

**Unsafe retries of writes.** A 429 usually means the request was refused, but a 500, 502, 503 or 504 on a write may have gone through before the error came back. Retrying `create_ticket` after a timeout can create two tickets. Leave write tools out of the retry path unless the API lets you send an idempotency key, a value that lets it recognize a request it already handled.

**Failures written as prose.** The text check only flags results that start with "error". A tool that answers "Sorry, I couldn't find that order" passes. If your tools answer in sentences, add their failure phrases to `errorFields()` in **Check tool result**.

For a full n8n agent workflow with validation and review branches, the [ticket triage lab](/blog/how-to-use-n8n-for-advanced-ai-workflow-automation) builds one you can run.

## Frequently asked questions

**Why does n8n show a run as successful when the agent's tool call failed?**

Because n8n marks a node as succeeded when it finishes without throwing an error, and a tool call can finish cleanly while failing. An API can answer 200 with an error in the body, a node set to keep going on errors turns a 404 into data, and an empty lookup is still a result. The model then writes its answer from whatever came back. The guard checks each tool's actual result instead of the node's color.

**Does the workflow need an API key or a model?**

No. It uses only core n8n nodes, holds no credentials and has no model node. The sample run uses nine made-up tool calls, so nothing leaves your n8n. Your agent workflow keeps its own model and credentials and calls the guard through an Execute Workflow node.

**Which failures does the guard retry?**

Only calls with a status of 408, 429, 500, 502, 503 or 504 that haven't used up their attempts. The default is two attempts. Those calls go to a retry placeholder that repeats nothing until you replace it, so until then a run whose only failures are retryable finishes green. Empty results, error fields, other status codes and missing fields go straight to the alert branch. Be careful with writes: a server error on a write may have gone through, so retrying can make the change twice unless the API takes an idempotency key.

**Why doesn't the Error Trigger fire when I test the workflow?**

n8n's Error Trigger docs say error workflows can't be tested through manual runs, and the workflow holding the Error Trigger must be published. The sample run stops at Fail the run, in red, and that's the expected result. To test the alert branch, publish the guard, call it from an agent workflow whose error workflow points at it, and use a case where a tool fails.


