Write custom code tools for n8n AI agents

This skill provides expert guidance for writing code inside @n8n/n8n-nodes-langchain.toolCode - the Custom Code Tool an AI Agent can invoke - which is explicitly not the regular workflow Code node despite looking identical in the editor. The two are different node types from different packages with different runtime contracts: the Code node (n8n-nodes-base.code) is invoked by the previous node in workflow flow, reads $input.all(), and returns an items array [{json: {...}}]; the Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode) is invoked by an AI Agent, reads a query string or object from the LLM, must return a plain string, has no $fromAI(), no exposed HTTP helper, and no getContext/$getWorkflowStaticData state access. Treating it like a Code node fails outright.

Essential rules: return a string (numbers auto-convert; anything else throws "The response property should be a string, but it is an object"); the input variable name is fixed as query in JavaScript or _query in Python and cannot be renamed; never call $fromAI() inside the sandbox (throws "No execution data available"); never return the [{json: {...}}] workflow-item format (throws "Wrong output type returned"); use a descriptive, verb-y tool name (letters/numbers/underscores only, n8n v1.1+) since the agent calls the tool by that name; and write a precise description, since the LLM decides whether to invoke the tool based on it alone.

The tool has two input modes controlled by specifyInputSchema. Unstructured mode (the default) passes the AI's input as a single string that the code must parse itself - often a JSON string if the description asks for one - simplest to set up but with no schema validation, best for prototypes or single-input tools. Structured mode (specifyInputSchema: true) turns the tool into a LangChain DynamicStructuredTool: the LLM sees a typed argument schema (defined via schemaType: "fromJson" with an example, on n8n v1.3+, or schemaType: "manual" with a hand-written JSON Schema) and passes a validated object directly, rejecting invalid calls before the code runs - best for production tools with multiple typed parameters. The return value must always be a string that the LLM reads as the tool's observation; the recommended pattern for anything beyond a trivial scalar is JSON.stringify()-ing a structured result. Errors are read by the agent itself, not just the workflow: thrown errors or JSON-string error objects both go back to the LLM, which typically corrects its call and retries - so error messages should be written for the LLM, stating what was wrong and what a valid call looks like, since a bare generic error wastes the retry.

Tool name and description are the contract the LLM actually sees, not documentation: the name must match [A-Za-z0-9_]+ (no spaces, hyphens, or emoji) and should be verb-y and descriptive (calculate_car_loan, not the useless default Code Tool); the description must explain when to use the tool and what to send, including a concrete JSON example for unstructured mode. Five top errors and fixes are documented: calling $fromAI() inside the sandbox (it's for other tool-enabled nodes, not toolCode - read query directly instead); returning a workflow-style array (return a string, JSON.stringify() for structured data); returning a plain object or array instead of a string (stringify or coerce it); the AI never calling the tool (rename it verb-y and state trigger conditions in the description); and the AI sending garbage into query (add a concrete JSON example, or switch to specifyInputSchema: true).

The Code Tool sandbox is narrower than the Code node sandbox: $input.all()/first()/item, $node["NodeName"], $json/$binary, this.helpers.httpRequest(), $jmespath(), this.getContext(), and $getWorkflowStaticData() are all unavailable, while DateTime (Luxon) is available in both. This makes the Code Tool suited only for pure computation; anything needing an HTTP call, API lookup, or cross-invocation state needs a different tool node - HTTP Request Tool for external calls, toolWorkflow (Call Sub-workflow Tool) for multi-step logic with full Code-node-sandbox access, or MCP/database tools for persistent state. Choosing between them: use Code Tool for pure deterministic computation, lightweight transformations the LLM shouldn't do itself, or inline code; use toolWorkflow when multiple typed parameters, this.helpers/credentials access, or reusable logic across agents are needed, without hand-writing a JSON Schema; use HTTP Request Tool when the tool is fundamentally a single API call with per-parameter $fromAI() bindings - as a rule of thumb, wanting $fromAI() at all means toolWorkflow, not toolCode, is the right choice.

Use 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 instead. 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.

Input is the LLM's tool call: a query string (unstructured mode) or a schema-validated query object (structured mode). Output must always be a string - typically a JSON.stringify()-encoded result for anything beyond a trivial scalar - wired into an AI Agent via the ai_tool connection type.

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

n8n-code-javascript (the Code node skill - most JS patterns transfer, but the I/O contract differs, so don't copy data-access code across), n8n-node-configuration (specifyInputSchema as a conditional field, inspected via get_node), n8n-workflow-patterns (Code Tool as the "local compute" option inside an AI-Agent-with-tools pattern), and n8n-validation-expert (the Code Tool's error signatures map directly to specific fixes).

n8n workflow builders writing AI-agent-invocable tools who need the Custom Code Tool's actual string-in/string-out contract - not the regular Code node's item-array contract - along with correct input-mode, error-handling, and tool-naming choices.