{"record":{"id":"a5a5e0293cd2e5b8","repo":"n8n-io/n8n","slug":"tool-name-tool-name-is-reserved-for-sdk-built","errorCode":null,"errorMessage":"Tool name \"${tool.name}\" is reserved for SDK built-in tools","messagePattern":"Tool name \"(.+?)\" is reserved for SDK built-in tools","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/agents/src/sdk/agent.ts","lineNumber":1388,"sourceCode":"\t\tthis.assertToolNameAvailable(tool.name);\n\t\tthis.assertReservedSdkBuiltInToolName(tool);\n\t}\n\n\tprivate assertToolNameAvailable(toolName: string): void {\n\t\tif (!this.hasRuntimeSkillTool || !RUNTIME_SKILL_TOOL_NAMES.has(toolName)) return;\n\n\t\tthrow new Error(`Tool name \"${toolName}\" is reserved for runtime skills`);\n\t}\n\n\tprivate assertReservedSdkBuiltInToolName(tool: BuiltTool): void {\n\t\tif (!SDK_RESERVED_BUILTIN_TOOL_NAMES.has(tool.name)) return;\n\t\tif (isDelegateSubAgentTool(tool)) {\n\t\t\tif (tool.name === DELEGATE_SUB_AGENT_TOOL_NAME) return;\n\t\t} else if (isSdkOwnedBuiltInTool(tool)) {\n\t\t\treturn;\n\t\t}\n\n\t\tthrow new Error(`Tool name \"${tool.name}\" is reserved for SDK built-in tools`);\n\t}\n\n\tprivate removeRuntimeSkillTools(): void {\n\t\tif (!this.hasRuntimeSkillTool) return;\n\n\t\tthis.tools = this.tools.filter((tool) => !RUNTIME_SKILL_TOOL_NAMES.has(tool.name));\n\t\tthis.hasRuntimeSkillTool = false;\n\t}\n}\n\nfunction resolveInlineSubAgentModelConfig(\n\trequest: DelegateSubAgentRequest,\n\toptions: {\n\t\tmodelConfig: ModelConfig;\n\t\tinlineSubAgentModelsByDifficulty?: Partial<Record<SubAgentTaskDifficulty, ModelConfig>>;\n\t},\n): ModelConfig {\n\tif (request.difficulty === undefined) {","sourceCodeStart":1370,"sourceCodeEnd":1406,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/agents/src/sdk/agent.ts#L1370-L1406","documentation":"Thrown by Agent.assertReservedSdkBuiltInToolName when a registered tool's name is in SDK_RESERVED_BUILTIN_TOOL_NAMES (currently 'delegate_subagent' and 'write_todos') but the tool is not the genuine SDK-built instance. Genuine status is detected by isDelegateSubAgentTool (for delegate_subagent) or isSdkOwnedBuiltInTool (metadata key 'sdkOwnedBuiltinTool' === true).","triggerScenarios":"Registering a hand-rolled tool whose name is 'delegate_subagent' or 'write_todos' without the SDK ownership metadata or delegate-tool branding. Triggered from .tool() / deferred tool registration through assertToolRegistrationAllowed.","commonSituations":"User copies the SDK built-in tool name by accident; a forked/modified tool loses the metadata stamp; constructing a delegate sub-agent tool with a custom factory that bypasses createDelegateSubAgentTool.","solutions":["Use createDelegateSubAgentTool / the official write-todos factory so the tool carries correct branding and metadata.","Rename your custom tool away from 'delegate_subagent' and 'write_todos'.","If you must wrap an SDK built-in, brand it with withSdkOwnedBuiltInMetadata or pass the already-branded instance."],"exampleFix":"// before\nagent.tool({ name: 'write_todos', execute: async () => ... });\n// after\nagent.tool({ name: 'my-todos', execute: async () => ... });","handlingStrategy":"validation","validationCode":"import { SDK_RESERVED_BUILTIN_TOOL_NAMES } from '@n8n/agents';\n\nfunction assertNotReservedBuiltin(name: string) {\n  if (SDK_RESERVED_BUILTIN_TOOL_NAMES.has(name)) {\n    throw new Error(`Tool name ${name} collides with SDK built-in; rename or use the factory.`);\n  }\n}","typeGuard":"function isReservedBuiltinName(name: string): boolean {\n  return name === 'delegate_subagent' || name === 'write_todos';\n}","tryCatchPattern":null,"preventionTips":["Prefer SDK factories (createDelegateSubAgentTool, createWriteTodosTool) over hand-built tools.","Maintain a deny-list of reserved names and lint tool registrations against it."],"tags":["tools","naming","reserved","sdk-builtin"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}