Giving tools to an n8n AI Agent: HTTP Request Tool, Code Tool and Workflow Tool

An AI Agent node with no tools is just an expensive chatbot: it can chat, summarize, rephrase — but it can't do anything. The difference between an agent that talks and an agent that acts comes down to a single connection, ai_tool, and three families of sub-nodes that feed it. This guide covers how to choose them, configure them, and above all how to write the descriptions their usefulness depends on — the point most workflows get wrong.

If you're still discovering n8n's cluster-node architecture, start with our Getting started with n8n's AI nodes guide, which covers the AI Agent node, chains and memory. Here, we assume the agent is already running and focus on the ai_tool connection.

The three families of tools

Under an AI Agent node's ai_tool slot, three sub-nodes cover nearly every need:

HTTP Request Tool (toolHttpRequest)

This is the most widely used tool in production: it wraps a standard HTTP request (method, URL, headers, body) and exposes it to the agent as an action capability. The agent decides on its own what values to inject into the configured fields — it can query a third-party API, write to a database through a REST API, or trigger a notification.

Concretely, this is the mechanism behind the questionnaire agent in our Compliance & Audit Pack: after each answer the user confirms, the agent calls a toolHttpRequest that posts to Supabase's REST API, with the file ID, the question asked, and the rephrased answer. The agent has no idea what Supabase is — it just knows, from the tool's description, that it needs to "record a validated questionnaire answer" after every confirmed exchange.

Custom Code Tool (toolCode)

The same JavaScript or Python sandbox as n8n's standard Code node, but with a different interface: the Code Tool exposes a typed input/output schema that the agent fills in itself, rather than a simple chain of items. This is the tool to reach for when the logic doesn't exist in any API — a business calculation, a format validation, a transformation specific to your operation.

Call n8n Workflow Tool (toolWorkflow)

This tool exposes an entire n8n workflow as a capability the agent can call. It's the most powerful of the three: it lets you reuse any existing workflow (including one that itself contains complex logic, database access, or another AI call) without duplicating its logic into a plain HTTP call or a snippet of code. It's also the building block for agent hierarchies: a toolWorkflow can point to a workflow that itself contains a specialized AI Agent — a "router" agent that delegates to "expert" sub-agents.

The field that decides everything: name and description

This is the most misunderstood point of the AI Agent in n8n: the model never sees your configuration. It reads neither the URL called by the HTTP Request Tool, nor the Code Tool's code, nor the content of a workflow wired in as a Workflow Tool. All it sees are two text fields — the tool's name and its description — and it's from those two fields alone that it decides whether to call it, when, and with what data.

A vague description like "Calls the API" or "Processes the data" dooms a tool to being ignored, or worse, called at the wrong moment with invented parameters. A good description answers three questions in one or two sentences:

• When should it be called? ("after each answer the user confirms", "when the question is about internal documentation")
• What data does it expect? (field names, their format)
• What does it return?, if the result needs to feed later reasoning.

Back to the Compliance & Audit Pack example: the description on the recording toolHttpRequest isn't "Saves to the database" — it's "Records a validated questionnaire answer in Supabase. Call this tool after EVERY answer the user confirms, with the file ID, the numbered question label, and the rephrased answer." Every word matters: the capitalized "EVERY" forces consistency, and listing the three expected fields keeps the agent from dropping one.

The same logic applies to a document-search tool: our RAG guide with n8n and Supabase pgvector recommends this exact kind of explicit naming for the Vector Store wired in tool mode — "Search the company's internal documentation" is enough for the agent to know when to trigger a search rather than answer from memory.

How many tools on a single agent?

Adding tools one by one feels risk-free — until the agent starts confusing two of them, or ignoring a relevant one buried in too long a list. In practice, selection reliability stays solid up to 5 to 7 tools on one agent; beyond that, the systemMessage needs real work to remove ambiguity between tools with overlapping scopes.

Two strategies to scale without losing precision:

1. Mutually exclusive descriptions. If two tools could plausibly answer the same intent (say, "look up a customer" on the CRM side and on the billing side), spell out each tool's exact scope in its description rather than relying on conversational context.
2. Split into several specialized agents. A "router" agent with a few broad tools, one of which is an AI Agent Tool (toolAiAgent) or a Workflow Tool pointing to an expert sub-agent (billing, support, compliance). Each sub-agent keeps a short, coherent tool list, which preserves selection precision at every level.

Since the Tools Agent (typeVersion 1.7+)

Since recent versions of the AI Agent, the agent defaults to being a Tools Agent: tool selection relies on the model's native function calling (OpenAI, Anthropic, etc.) rather than fragile text parsing. This is exactly what makes tool descriptions so decisive — they're passed to the model as-is, as function definitions, in the same format used to connect Claude or GPT to n8n. The maxIterations parameter (10 by default) caps the number of reason → call a tool → analyze the result cycles before the agent is forced to answer; lower it if your tools are slow or expensive.

Securing an agent that acts

An agent able to call a toolHttpRequest for writes — a POST, a PATCH, a DELETE — is no longer just a text generator: it's a system that triggers real side effects, potentially on the strength of a hallucination. Three concrete precautions:

• Limit the API key's rights to the strict scope the tool needs (a key that can only insert into one specific table, rather than an admin key shared with the rest of the workflow).
• Validate on the API side, not just in the prompt: a missing required field or an invalid format should be rejected by the called endpoint, not merely "politely requested" in the tool's description.
• Add a human approval step before the most sensitive actions (sending an external email, a payment, a deletion) rather than letting the agent act alone — the Wait node pattern with Slack buttons, covered in our article on human approval in n8n, fits naturally between the agent's decision and the tool's execution.

On the reliability side, a failed tool call (API down, timeout) shouldn't crash the whole workflow: the same recovery mechanisms as any other node — covered in our handling errors in n8n guide — apply to tool sub-nodes too.

Watching what the agent actually called

In n8n's execution panel, every tool call shows up as a distinct entry under the AI Agent node, with the exact parameters the model sent and the response it got back. That's the first debugging move when an agent misbehaves: before suspecting the model, check what it actually sent to the tool — a mis-named field in the Code Tool's schema, or an ambiguous description, explains the vast majority of unexpected behavior.

Wrapping up

An n8n AI Agent is only as capable as the tools you wire into it — and a tool is only as useful as its description. HTTP Request Tool to talk to an existing API, Code Tool for business logic that lives nowhere else, Workflow Tool to reuse or hierarchize entire workflows: the three cover nearly every case, as long as you treat each tool's name and description with the same care as an interface contract. Our Inbox AI Pack and Compliance & Audit Pack ship several of these tools already configured and documented — a solid starting point for seeing the pattern run on a real case before adapting it to yours.