Resources · n8n integration

n8n Code Tool nodeConfigure Code Tool in n8n.

The n8n Code Tool node turns a few lines of JavaScript or Python into a tool an AI agent can call on its own. Four parameters cover it: a name, a description the model reads to decide when to run it, the language and its code box, and an optional input schema.

Try the Code Tool node on n8nSee the 4 parameters

Verified Trustpilot reviews · AI, automation & growth agency

Why automate

What does the n8n Code Tool node actually do?

The Code Tool node is a sub-node, which means a small node you plug into a port of a bigger one rather than a step in the main flow. It holds a snippet of JavaScript or Python and hands it to an agent as a callable tool. When the model decides the tool fits the request, n8n runs the snippet with the text the model produced and passes the returned string back into the conversation.

The first use it earns is the calculation no model should be guessing at. A pricing rule, a VAT split, a working-day count between two dates: you write it once in the JavaScript box, describe it in one sentence, and the agent stops improvising arithmetic. The code reads the model's text through the query property and returns a single string, so the shape of the exchange stays predictable.

The second use is reformatting. An agent built on the AI Agent node often receives messy text and needs it normalized before anything else happens: a phone number cleaned up, a product reference parsed out of a sentence, a date turned into ISO. A dedicated node exists for none of that. Ten lines of Python do it, and the agent calls them only when it needs them.

The third use is a guarded input. Turn Specify Input Schema on and the model has to send a structured object that n8n validates before your code runs. That is what makes a code tool safe to put next to tools that write somewhere real, such as a row in Google Sheets or a message to Slack.

Prefer a different node when the job is not really code. Calling a service that already has an n8n node is better served by that node wired as a tool, and a transformation that happens on every item, not on the agent's decision, belongs in the main flow rather than here. A model that has to be talked into calling your function usually needs a sharper description, not more code.

Two limits are worth knowing before you build on it. Python runs in beta on this node, and the tool returns one string, so anything structured has to be serialized by your own code. The model provider behind the agent, OpenAI or another one, bills its own API calls; n8n adds nothing on top. If you want the wiring walked through end to end, the n8n training covers agents and their sub-nodes.

Connections

Where does the Code Tool node plug in?

n8n splits its AI nodes in two: a root node sits in the workflow and receives items, and sub-nodes hang off its ports. The Code Tool node is a sub-node, so it never runs by itself and has no main input.

Output (what it plugs into)

  • Toolai_tool
01ToolThis is the single port the node exposes. You drag its connector onto the tool port of a root node, and from that moment the model can list it, choose it and call it like any other tool in the same agent.

This is the single port the node exposes. You drag its connector onto the tool port of a root node, and from that moment the model can list it, choose it and call it like any other tool in the same agent.

Key parameters

  • Required: with nothing connected to it, the node is inert. A sub-node never executes on its own.
  • AI Agent: the usual host, a conversational or task-running agent.
  • AI Agent Tool: an agent itself wired as a tool of another agent.
  • MCP Server Trigger: when the tool has to be exposed to an outside client.
Use cases
the same snippet can be attached to a support agent and to an MCP server, without duplicating the code anywhere else.
Parameters

What are the 4 parameters of the Code Tool node?

The Code Tool node has 4 parameters. For each one: the node as you configure it in n8n, what the parameter changes, and our field notes.

01

Name

name

What you see in n8n

Notes & use cases

Along with the description, the name is what the model reads when it scans the tools available to it. It is a label for a machine, not a heading for a human, and the placeholder My_Tool shows the register expected: short, no spaces.

Key parameters

  • Name: a plain text field with nothing behind it. Something like compute_shipping lands better with a model than a full sentence would.
Use cases
an agent carrying several code tools needs names that cannot be confused, otherwise the model picks a neighbor and returns a result that looks right and is not.
02

Description

description

What you see in n8n

Notes & use cases

Everything the model knows about when to reach for this tool sits in this field. The node's own placeholder is a good template: it states the job, then states what the input string should contain, in that order.

Key parameters

  • Description: free text. Write the trigger condition and the expected input shape, for instance a sentence saying the tool returns a random color and that the input is a comma separated list of colors to exclude.
Use cases
a tool that never gets called is almost always a description problem. Naming the situation that should trigger it fixes more cases than rewriting the code.
03

Language

language

What you see in n8n

Notes & use cases

This selector decides which code box appears underneath, and it changes how your snippet reads the agent's input. Pick it before writing anything, because switching later means rewriting the accessor.

Key parameters

  • Language: two options, javaScript (JavaScript) and python (Python (Beta)).
  • JavaScript: the code box for the first option. The input arrives in the query property and the snippet has to return a single string.
  • Python: the box for the second. Same contract, except the input is read from _query.
Use cases
converting text to uppercase is the canonical one-liner, and it is enough to check the wiring before the real logic goes in.
04

Specify Input Schema

specifyInputSchema

What you see in n8n

Notes & use cases

Off, the tool takes whatever string the model writes. On, n8n requires the model to send input in a declared format and validates it against that schema before the code runs.

Key parameters

  • Specify Input Schema: the toggle itself. It reveals the three fields below.
  • Schema Type: fromJson (Generate From JSON Example) builds the schema from a sample object, manual (Define using JSON Schema) has you write it out.
  • JSON Example: the sample object the first mode reads.
  • Input Schema: the schema itself, in JSON Schema format. The $refs syntax is not supported.
Use cases
a tool expecting an order id and a quantity holds up far better with a schema.
Need help

Need help automating Code Tool with n8n?

A person reads every message.

FAQ

Code Tool node, the questions that come next

01Is the Code Tool node free to use in n8n?
Yes. It belongs to the n8n AI package, shipped with n8n, so there is nothing to install and no extra cost on the n8n side, on n8n Cloud as well as on a self-hosted instance under the Community Edition and its Sustainable Use license. A workflow behaves the same whether you run it from Docker, from npm, or from the hosted offer. What can cost money sits elsewhere: the agent this tool plugs into needs a chat model, and the provider of that model bills its own API calls under its own terms. n8n adds nothing on top of that.
02What do you need to authenticate before it works?
Nothing. The Code Tool node has no credential and no Authentication selector, which is why the page has no connection section at all. The account side of the equation is handled by the chat model sub-node plugged into the same agent: that one carries the provider credential, and it is the only place a key is entered. So the setup for this node is the code box, the description, and the connector dragged to a root node. If your tool runs but the agent never answers, look at the model sub-node and its key, not at this one.
03What are the limits of the n8n Code Tool node?
Three worth planning around. Python is marked beta on this node, so JavaScript is the steadier choice for anything you would rather not revisit. The exchange is string-shaped: the snippet reads the model's input from a single property and has to return one string, which means structured results need serializing yourself. And the input is only validated when Specify Input Schema is on, with the JSON Schema $refs syntax unsupported even then. This page describes version 1 of the node, the maximum in the catalog; an older workflow can display an earlier version with fewer options.
04What has to be connected, and where do you start?
At minimum, a root node. This node is a sub-node with a single Tool port and no main input, so it does nothing until its connector reaches an AI Agent, an AI Agent Tool, or an MCP Server Trigger. That root node in turn needs a chat model connected to it, with the provider credential on that sub-node. A good first build is small on purpose: one agent, one chat model, one code tool that lowercases whatever it receives, description written as a plain trigger sentence. Once the agent calls it reliably, swap the snippet for the logic you actually need.
05n8n or Make for a custom agent tool?
It depends on three things. Hosting: n8n runs on your own servers through Docker or npm, or on n8n Cloud, while Make is hosted only, so data residency decides it for some teams outright. Cost model: Make bills per operation, which is worth simulating against an agent that calls tools in loops. And control: a code tool means you own the logic in JavaScript or Python inside the workflow itself, which suits people comfortable writing a function. If visual building without code is the priority, that comfort matters less. Both are serious tools; the answer follows your constraints.
Hack'celeration Lab

Get our weekly integration tips.

No spam. Unsubscribe anytime.

Same platform

Other docs you might need on this stack.

Browse all integrations