Use an n8n Custom Node as an AI Agent Tool (usableAsTool)

You built a node. It works in a normal workflow. Then you put an AI Agent on the canvas, open its tools, type your node's name, and nothing comes up.

This guide fixes that, and then makes the agent good at using it. Getting the node into the list takes one line. Getting the agent to use it well takes three more things, and they're all about words you've already written.

It assumes you have a working node. If you don't, the Build your own n8n node series starts from an empty folder.

One line

In your node's description, next to its name and inputs:

defaults: { name: 'Acme CRM' },
usableAsTool: true,
inputs: [NodeConnectionTypes.Main],
outputs: [NodeConnectionTypes.Main],

When n8n starts and loads your node, it makes a copy of it for agents. The copy:

• gets "Tool" added to its name, so "Acme CRM" becomes "Acme CRM Tool"
• loses its input, because an agent doesn't pass items in, it calls the tool
• gets an output that plugs into the agent's Tool connector

You don't write the copy, and your file doesn't change. You get two nodes in the panel instead of one.

The setting you can delete

If you've looked this up before, you were probably told to set an environment variable, N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE, to let community nodes be used as tools.

You don't need it. It was added as a switch in early 2025, and a few weeks later n8n removed it and turned the behaviour on for everyone, in version 1.85.0. On anything newer, setting it does nothing.

So if you still see an error like "Unrecognized node type", with a type ending in Tool, the setting isn't the problem. It means n8n never made the tool copy. Check which version of your package n8n has actually loaded, and that the line is in it. It's usually an old build.

What the model reads: the tool description

When your node is used as a tool, it gets a Tool Description setting at the top, set to automatic by default. That's the sentence the model reads to decide whether to call your tool.

By default it's built from your code. n8n takes the action text of the chosen operation and adds "in" and your node's name:

{
  name: 'Create',
  value: 'create',
  action: 'Create contact',
}

becomes "Create contact in Acme CRM."

If you did the naming work from Part 6, you're already done. That action line, which felt like a small detail, is now an instruction an AI reads. If you never wrote one, n8n falls back to the raw operation and resource values. It still works; it just reads like a database column. Users can type their own description, but most leave the default.

Who fills in the fields

Each field of the tool gets a small button at its end. Click it, and the model fills that field in every time the agent calls the tool. Behind the scenes it's an expression using $fromAI.

What decides how well the model does that: n8n names the value after your field's label. The model is asked for "Email" or "First Name". If your label is "val" or "Field 1", the model is guessing. Clear labels and descriptions are now prompt text.

And one thing that surprised us: dropdowns don't get the button. The model can't choose the Resource or the Operation. The person building the workflow sets those.

So one tool node does one job. If you want the agent to search contacts and also create them, add your node twice, once per operation. An agent with two clear tools does better than one with a vague tool.

Two tools, one agent

Put it together: a chat trigger, an AI Agent, and two copies of the node as tools, one that searches contacts and one that creates them.

Ask the agent to "add Priya Shah from Northwind as a contact." It reads both tool descriptions and decides what to call. With a search tool next to the create tool, it can check whether she's already there first. Whether it does depends on the model and your prompt, so if it matters, say it in the agent's instructions.

Either way, the agent has never seen your API docs. All it has are the words you wrote in the code.

Why verified nodes get found

If you build an API, there's one more reason to do this. Since n8n 2.33, when someone picks tools for an agent, n8n lists verified community nodes there before they've been installed. Unverified nodes only show up if the user already knows the name and searches for it.

So a verified node marked as a tool gets found by people who never went looking for you. That's the case for the verification checklist, in one screen.

Recap

• usableAsTool: true makes the tool version of your node.
• The old environment variable can go.
• Your action text becomes the tool's description.
• Your field labels are what the model is asked to fill in.
• Dropdowns stay with the workflow builder, so use one tool node per job.

One more thing. Nodes generated with NativeShip, the tool we build, come out with usableAsTool already set, so there's no line to remember.