n8n Custom Code Tool

When to Use

Use this skill specifically for code executed by the AI-agent-callable n8n Custom Code Tool. Use the separate JavaScript or Python Code-node skills for ordinary workflow Code nodes.

Do not hardcode secrets or accept arbitrary executable code from untrusted input. Constrain inputs with a schema, validate outputs, allowlist any network destinations, and ask before testing a tool whose code can write data or invoke an external service.

Expert guidance for writing code inside @n8n/n8n-nodes-langchain.toolCode — the tool an AI Agent can invoke, not the regular workflow Code node.

⚠️ This is NOT the Code node

The Custom Code Tool looks like a Code node in the editor — same JavaScript editor, similar layout — but it is a completely different node from a different package with a different runtime contract.

If you treat it like a Code node, it fails. The rest of this skill covers the Code Tool's actual contract.

Quick Start

Minimal JavaScript Code Tool

// `query` is whatever the AI sent (a string by default)
return `You asked: ${query}`;

Minimal Python Code Tool

# `_query` is whatever the AI sent (a string by default)
return f"You asked: {_query}"

Essential Rules

1. Return a string. Numbers are auto-converted. Anything else throws "The response property should be a string, but it is an object".
2. Input variable is fixed: query (JS), _query (Python). You cannot rename it.
3. Do NOT use $fromAI() inside the Code Tool sandbox — it throws "No execution data available".
4. Do NOT use [{json: {...}}] return format — that's for Code nodes. Throws "Wrong output type returned".
5. Use a descriptive tool name (letters/numbers/underscores, v1.1+). The agent calls the tool by its name.
6. Write a precise description — the LLM decides whether to invoke the tool based on it.

The Two Input Modes

The Code Tool has two input shapes, controlled by specifyInputSchema:

Mode 1: Unstructured (default, specifyInputSchema: false)

The AI passes a single string as query. If you need multiple fields, the AI has to stuff them into that one string and you parse them out. In practice, LLMs will happily pass a JSON string if your description tells them to.

// Parse a JSON string the AI sent
let params;
try {
  params = typeof query === 'string' ? JSON.parse(query) : query;
} catch (e) {
  throw new Error('Expected a JSON object. Parser said: ' + e.message);
}
const price = Number(params.price);
const months = Number(params.months);
// ...
return JSON.stringify({ monthly_payment: /* ... */ });

Pros: simplest to set up, one field to describe. Cons: no schema validation — if the LLM forgets a field, the tool throws at runtime.

Best for: quick prototypes, tools with one natural input (a question, a URL, a text blob).

Mode 2: Structured (specifyInputSchema: true)

The tool becomes a LangChain DynamicStructuredTool. The LLM sees a typed argument schema and passes a validated object as query. You access fields directly.

// query is now an object matching your schema
const price = query.price;
const months = query.months;
const residual_percent = query.residual_percent;

const monthly = computeAnnuity(price, months, residual_percent);
return JSON.stringify({ monthly_payment: monthly });

Schema is defined via either:

• schemaType: "fromJson" + jsonSchemaExample (n8n v≥1.3) — paste an example JSON, n8n infers the schema
• schemaType: "manual" + inputSchema — write a full JSON Schema yourself

Pros: LLM gets type hints, invalid calls rejected before your code runs, cleaner code.

…