This is page 56 of 59. Use http://codebase.md/czlonkowski/n8n-mcp?lines=true&page={x} to view the full context.
# Directory Structure
```
├── _config.yml
├── .claude
│ └── agents
│ ├── code-reviewer.md
│ ├── context-manager.md
│ ├── debugger.md
│ ├── deployment-engineer.md
│ ├── mcp-backend-engineer.md
│ ├── n8n-mcp-tester.md
│ ├── technical-researcher.md
│ └── test-automator.md
├── .dockerignore
├── .env.docker
├── .env.example
├── .env.n8n.example
├── .env.test
├── .env.test.example
├── .github
│ ├── ABOUT.md
│ ├── BENCHMARK_THRESHOLDS.md
│ ├── FUNDING.yml
│ ├── gh-pages.yml
│ ├── secret_scanning.yml
│ └── workflows
│ ├── benchmark-pr.yml
│ ├── benchmark.yml
│ ├── docker-build-fast.yml
│ ├── docker-build-n8n.yml
│ ├── docker-build.yml
│ ├── release.yml
│ ├── test.yml
│ └── update-n8n-deps.yml
├── .gitignore
├── .npmignore
├── ATTRIBUTION.md
├── CHANGELOG.md
├── CLAUDE.md
├── codecov.yml
├── coverage.json
├── data
│ ├── .gitkeep
│ ├── nodes.db
│ ├── nodes.db-shm
│ ├── nodes.db-wal
│ └── templates.db
├── deploy
│ └── quick-deploy-n8n.sh
├── docker
│ ├── docker-entrypoint.sh
│ ├── n8n-mcp
│ ├── parse-config.js
│ └── README.md
├── docker-compose.buildkit.yml
├── docker-compose.extract.yml
├── docker-compose.n8n.yml
├── docker-compose.override.yml.example
├── docker-compose.test-n8n.yml
├── docker-compose.yml
├── Dockerfile
├── Dockerfile.railway
├── Dockerfile.test
├── docs
│ ├── AUTOMATED_RELEASES.md
│ ├── BENCHMARKS.md
│ ├── CHANGELOG.md
│ ├── CLAUDE_CODE_SETUP.md
│ ├── CLAUDE_INTERVIEW.md
│ ├── CODECOV_SETUP.md
│ ├── CODEX_SETUP.md
│ ├── CURSOR_SETUP.md
│ ├── DEPENDENCY_UPDATES.md
│ ├── DOCKER_README.md
│ ├── DOCKER_TROUBLESHOOTING.md
│ ├── FINAL_AI_VALIDATION_SPEC.md
│ ├── FLEXIBLE_INSTANCE_CONFIGURATION.md
│ ├── HTTP_DEPLOYMENT.md
│ ├── img
│ │ ├── cc_command.png
│ │ ├── cc_connected.png
│ │ ├── codex_connected.png
│ │ ├── cursor_tut.png
│ │ ├── Railway_api.png
│ │ ├── Railway_server_address.png
│ │ ├── vsc_ghcp_chat_agent_mode.png
│ │ ├── vsc_ghcp_chat_instruction_files.png
│ │ ├── vsc_ghcp_chat_thinking_tool.png
│ │ └── windsurf_tut.png
│ ├── INSTALLATION.md
│ ├── LIBRARY_USAGE.md
│ ├── local
│ │ ├── DEEP_DIVE_ANALYSIS_2025-10-02.md
│ │ ├── DEEP_DIVE_ANALYSIS_README.md
│ │ ├── Deep_dive_p1_p2.md
│ │ ├── integration-testing-plan.md
│ │ ├── integration-tests-phase1-summary.md
│ │ ├── N8N_AI_WORKFLOW_BUILDER_ANALYSIS.md
│ │ ├── P0_IMPLEMENTATION_PLAN.md
│ │ └── TEMPLATE_MINING_ANALYSIS.md
│ ├── MCP_ESSENTIALS_README.md
│ ├── MCP_QUICK_START_GUIDE.md
│ ├── N8N_DEPLOYMENT.md
│ ├── RAILWAY_DEPLOYMENT.md
│ ├── README_CLAUDE_SETUP.md
│ ├── README.md
│ ├── tools-documentation-usage.md
│ ├── VS_CODE_PROJECT_SETUP.md
│ ├── WINDSURF_SETUP.md
│ └── workflow-diff-examples.md
├── examples
│ └── enhanced-documentation-demo.js
├── fetch_log.txt
├── LICENSE
├── MEMORY_N8N_UPDATE.md
├── MEMORY_TEMPLATE_UPDATE.md
├── monitor_fetch.sh
├── N8N_HTTP_STREAMABLE_SETUP.md
├── n8n-nodes.db
├── P0-R3-TEST-PLAN.md
├── package-lock.json
├── package.json
├── package.runtime.json
├── PRIVACY.md
├── railway.json
├── README.md
├── renovate.json
├── scripts
│ ├── analyze-optimization.sh
│ ├── audit-schema-coverage.ts
│ ├── build-optimized.sh
│ ├── compare-benchmarks.js
│ ├── demo-optimization.sh
│ ├── deploy-http.sh
│ ├── deploy-to-vm.sh
│ ├── export-webhook-workflows.ts
│ ├── extract-changelog.js
│ ├── extract-from-docker.js
│ ├── extract-nodes-docker.sh
│ ├── extract-nodes-simple.sh
│ ├── format-benchmark-results.js
│ ├── generate-benchmark-stub.js
│ ├── generate-detailed-reports.js
│ ├── generate-test-summary.js
│ ├── http-bridge.js
│ ├── mcp-http-client.js
│ ├── migrate-nodes-fts.ts
│ ├── migrate-tool-docs.ts
│ ├── n8n-docs-mcp.service
│ ├── nginx-n8n-mcp.conf
│ ├── prebuild-fts5.ts
│ ├── prepare-release.js
│ ├── publish-npm-quick.sh
│ ├── publish-npm.sh
│ ├── quick-test.ts
│ ├── run-benchmarks-ci.js
│ ├── sync-runtime-version.js
│ ├── test-ai-validation-debug.ts
│ ├── test-code-node-enhancements.ts
│ ├── test-code-node-fixes.ts
│ ├── test-docker-config.sh
│ ├── test-docker-fingerprint.ts
│ ├── test-docker-optimization.sh
│ ├── test-docker.sh
│ ├── test-empty-connection-validation.ts
│ ├── test-error-message-tracking.ts
│ ├── test-error-output-validation.ts
│ ├── test-error-validation.js
│ ├── test-essentials.ts
│ ├── test-expression-code-validation.ts
│ ├── test-expression-format-validation.js
│ ├── test-fts5-search.ts
│ ├── test-fuzzy-fix.ts
│ ├── test-fuzzy-simple.ts
│ ├── test-helpers-validation.ts
│ ├── test-http-search.ts
│ ├── test-http.sh
│ ├── test-jmespath-validation.ts
│ ├── test-multi-tenant-simple.ts
│ ├── test-multi-tenant.ts
│ ├── test-n8n-integration.sh
│ ├── test-node-info.js
│ ├── test-node-type-validation.ts
│ ├── test-nodes-base-prefix.ts
│ ├── test-operation-validation.ts
│ ├── test-optimized-docker.sh
│ ├── test-release-automation.js
│ ├── test-search-improvements.ts
│ ├── test-security.ts
│ ├── test-single-session.sh
│ ├── test-sqljs-triggers.ts
│ ├── test-telemetry-debug.ts
│ ├── test-telemetry-direct.ts
│ ├── test-telemetry-env.ts
│ ├── test-telemetry-integration.ts
│ ├── test-telemetry-no-select.ts
│ ├── test-telemetry-security.ts
│ ├── test-telemetry-simple.ts
│ ├── test-typeversion-validation.ts
│ ├── test-url-configuration.ts
│ ├── test-user-id-persistence.ts
│ ├── test-webhook-validation.ts
│ ├── test-workflow-insert.ts
│ ├── test-workflow-sanitizer.ts
│ ├── test-workflow-tracking-debug.ts
│ ├── update-and-publish-prep.sh
│ ├── update-n8n-deps.js
│ ├── update-readme-version.js
│ ├── vitest-benchmark-json-reporter.js
│ └── vitest-benchmark-reporter.ts
├── SECURITY.md
├── src
│ ├── config
│ │ └── n8n-api.ts
│ ├── data
│ │ └── canonical-ai-tool-examples.json
│ ├── database
│ │ ├── database-adapter.ts
│ │ ├── migrations
│ │ │ └── add-template-node-configs.sql
│ │ ├── node-repository.ts
│ │ ├── nodes.db
│ │ ├── schema-optimized.sql
│ │ └── schema.sql
│ ├── errors
│ │ └── validation-service-error.ts
│ ├── http-server-single-session.ts
│ ├── http-server.ts
│ ├── index.ts
│ ├── loaders
│ │ └── node-loader.ts
│ ├── mappers
│ │ └── docs-mapper.ts
│ ├── mcp
│ │ ├── handlers-n8n-manager.ts
│ │ ├── handlers-workflow-diff.ts
│ │ ├── index.ts
│ │ ├── server.ts
│ │ ├── stdio-wrapper.ts
│ │ ├── tool-docs
│ │ │ ├── configuration
│ │ │ │ ├── get-node-as-tool-info.ts
│ │ │ │ ├── get-node-documentation.ts
│ │ │ │ ├── get-node-essentials.ts
│ │ │ │ ├── get-node-info.ts
│ │ │ │ ├── get-property-dependencies.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── search-node-properties.ts
│ │ │ ├── discovery
│ │ │ │ ├── get-database-statistics.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── list-ai-tools.ts
│ │ │ │ ├── list-nodes.ts
│ │ │ │ └── search-nodes.ts
│ │ │ ├── guides
│ │ │ │ ├── ai-agents-guide.ts
│ │ │ │ └── index.ts
│ │ │ ├── index.ts
│ │ │ ├── system
│ │ │ │ ├── index.ts
│ │ │ │ ├── n8n-diagnostic.ts
│ │ │ │ ├── n8n-health-check.ts
│ │ │ │ ├── n8n-list-available-tools.ts
│ │ │ │ └── tools-documentation.ts
│ │ │ ├── templates
│ │ │ │ ├── get-template.ts
│ │ │ │ ├── get-templates-for-task.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── list-node-templates.ts
│ │ │ │ ├── list-tasks.ts
│ │ │ │ ├── search-templates-by-metadata.ts
│ │ │ │ └── search-templates.ts
│ │ │ ├── types.ts
│ │ │ ├── validation
│ │ │ │ ├── index.ts
│ │ │ │ ├── validate-node-minimal.ts
│ │ │ │ ├── validate-node-operation.ts
│ │ │ │ ├── validate-workflow-connections.ts
│ │ │ │ ├── validate-workflow-expressions.ts
│ │ │ │ └── validate-workflow.ts
│ │ │ └── workflow_management
│ │ │ ├── index.ts
│ │ │ ├── n8n-autofix-workflow.ts
│ │ │ ├── n8n-create-workflow.ts
│ │ │ ├── n8n-delete-execution.ts
│ │ │ ├── n8n-delete-workflow.ts
│ │ │ ├── n8n-get-execution.ts
│ │ │ ├── n8n-get-workflow-details.ts
│ │ │ ├── n8n-get-workflow-minimal.ts
│ │ │ ├── n8n-get-workflow-structure.ts
│ │ │ ├── n8n-get-workflow.ts
│ │ │ ├── n8n-list-executions.ts
│ │ │ ├── n8n-list-workflows.ts
│ │ │ ├── n8n-trigger-webhook-workflow.ts
│ │ │ ├── n8n-update-full-workflow.ts
│ │ │ ├── n8n-update-partial-workflow.ts
│ │ │ └── n8n-validate-workflow.ts
│ │ ├── tools-documentation.ts
│ │ ├── tools-n8n-friendly.ts
│ │ ├── tools-n8n-manager.ts
│ │ ├── tools.ts
│ │ └── workflow-examples.ts
│ ├── mcp-engine.ts
│ ├── mcp-tools-engine.ts
│ ├── n8n
│ │ ├── MCPApi.credentials.ts
│ │ └── MCPNode.node.ts
│ ├── parsers
│ │ ├── node-parser.ts
│ │ ├── property-extractor.ts
│ │ └── simple-parser.ts
│ ├── scripts
│ │ ├── debug-http-search.ts
│ │ ├── extract-from-docker.ts
│ │ ├── fetch-templates-robust.ts
│ │ ├── fetch-templates.ts
│ │ ├── rebuild-database.ts
│ │ ├── rebuild-optimized.ts
│ │ ├── rebuild.ts
│ │ ├── sanitize-templates.ts
│ │ ├── seed-canonical-ai-examples.ts
│ │ ├── test-autofix-documentation.ts
│ │ ├── test-autofix-workflow.ts
│ │ ├── test-execution-filtering.ts
│ │ ├── test-node-suggestions.ts
│ │ ├── test-protocol-negotiation.ts
│ │ ├── test-summary.ts
│ │ ├── test-webhook-autofix.ts
│ │ ├── validate.ts
│ │ └── validation-summary.ts
│ ├── services
│ │ ├── ai-node-validator.ts
│ │ ├── ai-tool-validators.ts
│ │ ├── confidence-scorer.ts
│ │ ├── config-validator.ts
│ │ ├── enhanced-config-validator.ts
│ │ ├── example-generator.ts
│ │ ├── execution-processor.ts
│ │ ├── expression-format-validator.ts
│ │ ├── expression-validator.ts
│ │ ├── n8n-api-client.ts
│ │ ├── n8n-validation.ts
│ │ ├── node-documentation-service.ts
│ │ ├── node-similarity-service.ts
│ │ ├── node-specific-validators.ts
│ │ ├── operation-similarity-service.ts
│ │ ├── property-dependencies.ts
│ │ ├── property-filter.ts
│ │ ├── resource-similarity-service.ts
│ │ ├── sqlite-storage-service.ts
│ │ ├── task-templates.ts
│ │ ├── universal-expression-validator.ts
│ │ ├── workflow-auto-fixer.ts
│ │ ├── workflow-diff-engine.ts
│ │ └── workflow-validator.ts
│ ├── telemetry
│ │ ├── batch-processor.ts
│ │ ├── config-manager.ts
│ │ ├── early-error-logger.ts
│ │ ├── error-sanitization-utils.ts
│ │ ├── error-sanitizer.ts
│ │ ├── event-tracker.ts
│ │ ├── event-validator.ts
│ │ ├── index.ts
│ │ ├── performance-monitor.ts
│ │ ├── rate-limiter.ts
│ │ ├── startup-checkpoints.ts
│ │ ├── telemetry-error.ts
│ │ ├── telemetry-manager.ts
│ │ ├── telemetry-types.ts
│ │ └── workflow-sanitizer.ts
│ ├── templates
│ │ ├── batch-processor.ts
│ │ ├── metadata-generator.ts
│ │ ├── README.md
│ │ ├── template-fetcher.ts
│ │ ├── template-repository.ts
│ │ └── template-service.ts
│ ├── types
│ │ ├── index.ts
│ │ ├── instance-context.ts
│ │ ├── n8n-api.ts
│ │ ├── node-types.ts
│ │ └── workflow-diff.ts
│ └── utils
│ ├── auth.ts
│ ├── bridge.ts
│ ├── cache-utils.ts
│ ├── console-manager.ts
│ ├── documentation-fetcher.ts
│ ├── enhanced-documentation-fetcher.ts
│ ├── error-handler.ts
│ ├── example-generator.ts
│ ├── fixed-collection-validator.ts
│ ├── logger.ts
│ ├── mcp-client.ts
│ ├── n8n-errors.ts
│ ├── node-source-extractor.ts
│ ├── node-type-normalizer.ts
│ ├── node-type-utils.ts
│ ├── node-utils.ts
│ ├── npm-version-checker.ts
│ ├── protocol-version.ts
│ ├── simple-cache.ts
│ ├── ssrf-protection.ts
│ ├── template-node-resolver.ts
│ ├── template-sanitizer.ts
│ ├── url-detector.ts
│ ├── validation-schemas.ts
│ └── version.ts
├── test-output.txt
├── test-reinit-fix.sh
├── tests
│ ├── __snapshots__
│ │ └── .gitkeep
│ ├── auth.test.ts
│ ├── benchmarks
│ │ ├── database-queries.bench.ts
│ │ ├── index.ts
│ │ ├── mcp-tools.bench.ts
│ │ ├── mcp-tools.bench.ts.disabled
│ │ ├── mcp-tools.bench.ts.skip
│ │ ├── node-loading.bench.ts.disabled
│ │ ├── README.md
│ │ ├── search-operations.bench.ts.disabled
│ │ └── validation-performance.bench.ts.disabled
│ ├── bridge.test.ts
│ ├── comprehensive-extraction-test.js
│ ├── data
│ │ └── .gitkeep
│ ├── debug-slack-doc.js
│ ├── demo-enhanced-documentation.js
│ ├── docker-tests-README.md
│ ├── error-handler.test.ts
│ ├── examples
│ │ └── using-database-utils.test.ts
│ ├── extracted-nodes-db
│ │ ├── database-import.json
│ │ ├── extraction-report.json
│ │ ├── insert-nodes.sql
│ │ ├── n8n-nodes-base__Airtable.json
│ │ ├── n8n-nodes-base__Discord.json
│ │ ├── n8n-nodes-base__Function.json
│ │ ├── n8n-nodes-base__HttpRequest.json
│ │ ├── n8n-nodes-base__If.json
│ │ ├── n8n-nodes-base__Slack.json
│ │ ├── n8n-nodes-base__SplitInBatches.json
│ │ └── n8n-nodes-base__Webhook.json
│ ├── factories
│ │ ├── node-factory.ts
│ │ └── property-definition-factory.ts
│ ├── fixtures
│ │ ├── .gitkeep
│ │ ├── database
│ │ │ └── test-nodes.json
│ │ ├── factories
│ │ │ ├── node.factory.ts
│ │ │ └── parser-node.factory.ts
│ │ └── template-configs.ts
│ ├── helpers
│ │ └── env-helpers.ts
│ ├── http-server-auth.test.ts
│ ├── integration
│ │ ├── ai-validation
│ │ │ ├── ai-agent-validation.test.ts
│ │ │ ├── ai-tool-validation.test.ts
│ │ │ ├── chat-trigger-validation.test.ts
│ │ │ ├── e2e-validation.test.ts
│ │ │ ├── helpers.ts
│ │ │ ├── llm-chain-validation.test.ts
│ │ │ ├── README.md
│ │ │ └── TEST_REPORT.md
│ │ ├── ci
│ │ │ └── database-population.test.ts
│ │ ├── database
│ │ │ ├── connection-management.test.ts
│ │ │ ├── empty-database.test.ts
│ │ │ ├── fts5-search.test.ts
│ │ │ ├── node-fts5-search.test.ts
│ │ │ ├── node-repository.test.ts
│ │ │ ├── performance.test.ts
│ │ │ ├── template-node-configs.test.ts
│ │ │ ├── template-repository.test.ts
│ │ │ ├── test-utils.ts
│ │ │ └── transactions.test.ts
│ │ ├── database-integration.test.ts
│ │ ├── docker
│ │ │ ├── docker-config.test.ts
│ │ │ ├── docker-entrypoint.test.ts
│ │ │ └── test-helpers.ts
│ │ ├── flexible-instance-config.test.ts
│ │ ├── mcp
│ │ │ └── template-examples-e2e.test.ts
│ │ ├── mcp-protocol
│ │ │ ├── basic-connection.test.ts
│ │ │ ├── error-handling.test.ts
│ │ │ ├── performance.test.ts
│ │ │ ├── protocol-compliance.test.ts
│ │ │ ├── README.md
│ │ │ ├── session-management.test.ts
│ │ │ ├── test-helpers.ts
│ │ │ ├── tool-invocation.test.ts
│ │ │ └── workflow-error-validation.test.ts
│ │ ├── msw-setup.test.ts
│ │ ├── n8n-api
│ │ │ ├── executions
│ │ │ │ ├── delete-execution.test.ts
│ │ │ │ ├── get-execution.test.ts
│ │ │ │ ├── list-executions.test.ts
│ │ │ │ └── trigger-webhook.test.ts
│ │ │ ├── scripts
│ │ │ │ └── cleanup-orphans.ts
│ │ │ ├── system
│ │ │ │ ├── diagnostic.test.ts
│ │ │ │ ├── health-check.test.ts
│ │ │ │ └── list-tools.test.ts
│ │ │ ├── test-connection.ts
│ │ │ ├── types
│ │ │ │ └── mcp-responses.ts
│ │ │ ├── utils
│ │ │ │ ├── cleanup-helpers.ts
│ │ │ │ ├── credentials.ts
│ │ │ │ ├── factories.ts
│ │ │ │ ├── fixtures.ts
│ │ │ │ ├── mcp-context.ts
│ │ │ │ ├── n8n-client.ts
│ │ │ │ ├── node-repository.ts
│ │ │ │ ├── response-types.ts
│ │ │ │ ├── test-context.ts
│ │ │ │ └── webhook-workflows.ts
│ │ │ └── workflows
│ │ │ ├── autofix-workflow.test.ts
│ │ │ ├── create-workflow.test.ts
│ │ │ ├── delete-workflow.test.ts
│ │ │ ├── get-workflow-details.test.ts
│ │ │ ├── get-workflow-minimal.test.ts
│ │ │ ├── get-workflow-structure.test.ts
│ │ │ ├── get-workflow.test.ts
│ │ │ ├── list-workflows.test.ts
│ │ │ ├── smart-parameters.test.ts
│ │ │ ├── update-partial-workflow.test.ts
│ │ │ ├── update-workflow.test.ts
│ │ │ └── validate-workflow.test.ts
│ │ ├── security
│ │ │ ├── command-injection-prevention.test.ts
│ │ │ └── rate-limiting.test.ts
│ │ ├── setup
│ │ │ ├── integration-setup.ts
│ │ │ └── msw-test-server.ts
│ │ ├── telemetry
│ │ │ ├── docker-user-id-stability.test.ts
│ │ │ └── mcp-telemetry.test.ts
│ │ ├── templates
│ │ │ └── metadata-operations.test.ts
│ │ └── workflow-creation-node-type-format.test.ts
│ ├── logger.test.ts
│ ├── MOCKING_STRATEGY.md
│ ├── mocks
│ │ ├── n8n-api
│ │ │ ├── data
│ │ │ │ ├── credentials.ts
│ │ │ │ ├── executions.ts
│ │ │ │ └── workflows.ts
│ │ │ ├── handlers.ts
│ │ │ └── index.ts
│ │ └── README.md
│ ├── node-storage-export.json
│ ├── setup
│ │ ├── global-setup.ts
│ │ ├── msw-setup.ts
│ │ ├── TEST_ENV_DOCUMENTATION.md
│ │ └── test-env.ts
│ ├── test-database-extraction.js
│ ├── test-direct-extraction.js
│ ├── test-enhanced-documentation.js
│ ├── test-enhanced-integration.js
│ ├── test-mcp-extraction.js
│ ├── test-mcp-server-extraction.js
│ ├── test-mcp-tools-integration.js
│ ├── test-node-documentation-service.js
│ ├── test-node-list.js
│ ├── test-package-info.js
│ ├── test-parsing-operations.js
│ ├── test-slack-node-complete.js
│ ├── test-small-rebuild.js
│ ├── test-sqlite-search.js
│ ├── test-storage-system.js
│ ├── unit
│ │ ├── __mocks__
│ │ │ ├── n8n-nodes-base.test.ts
│ │ │ ├── n8n-nodes-base.ts
│ │ │ └── README.md
│ │ ├── database
│ │ │ ├── __mocks__
│ │ │ │ └── better-sqlite3.ts
│ │ │ ├── database-adapter-unit.test.ts
│ │ │ ├── node-repository-core.test.ts
│ │ │ ├── node-repository-operations.test.ts
│ │ │ ├── node-repository-outputs.test.ts
│ │ │ ├── README.md
│ │ │ └── template-repository-core.test.ts
│ │ ├── docker
│ │ │ ├── config-security.test.ts
│ │ │ ├── edge-cases.test.ts
│ │ │ ├── parse-config.test.ts
│ │ │ └── serve-command.test.ts
│ │ ├── errors
│ │ │ └── validation-service-error.test.ts
│ │ ├── examples
│ │ │ └── using-n8n-nodes-base-mock.test.ts
│ │ ├── flexible-instance-security-advanced.test.ts
│ │ ├── flexible-instance-security.test.ts
│ │ ├── http-server
│ │ │ └── multi-tenant-support.test.ts
│ │ ├── http-server-n8n-mode.test.ts
│ │ ├── http-server-n8n-reinit.test.ts
│ │ ├── http-server-session-management.test.ts
│ │ ├── loaders
│ │ │ └── node-loader.test.ts
│ │ ├── mappers
│ │ │ └── docs-mapper.test.ts
│ │ ├── mcp
│ │ │ ├── get-node-essentials-examples.test.ts
│ │ │ ├── handlers-n8n-manager-simple.test.ts
│ │ │ ├── handlers-n8n-manager.test.ts
│ │ │ ├── handlers-workflow-diff.test.ts
│ │ │ ├── lru-cache-behavior.test.ts
│ │ │ ├── multi-tenant-tool-listing.test.ts.disabled
│ │ │ ├── parameter-validation.test.ts
│ │ │ ├── search-nodes-examples.test.ts
│ │ │ ├── tools-documentation.test.ts
│ │ │ └── tools.test.ts
│ │ ├── monitoring
│ │ │ └── cache-metrics.test.ts
│ │ ├── MULTI_TENANT_TEST_COVERAGE.md
│ │ ├── multi-tenant-integration.test.ts
│ │ ├── parsers
│ │ │ ├── node-parser-outputs.test.ts
│ │ │ ├── node-parser.test.ts
│ │ │ ├── property-extractor.test.ts
│ │ │ └── simple-parser.test.ts
│ │ ├── scripts
│ │ │ └── fetch-templates-extraction.test.ts
│ │ ├── services
│ │ │ ├── ai-node-validator.test.ts
│ │ │ ├── ai-tool-validators.test.ts
│ │ │ ├── confidence-scorer.test.ts
│ │ │ ├── config-validator-basic.test.ts
│ │ │ ├── config-validator-edge-cases.test.ts
│ │ │ ├── config-validator-node-specific.test.ts
│ │ │ ├── config-validator-security.test.ts
│ │ │ ├── debug-validator.test.ts
│ │ │ ├── enhanced-config-validator-integration.test.ts
│ │ │ ├── enhanced-config-validator-operations.test.ts
│ │ │ ├── enhanced-config-validator.test.ts
│ │ │ ├── example-generator.test.ts
│ │ │ ├── execution-processor.test.ts
│ │ │ ├── expression-format-validator.test.ts
│ │ │ ├── expression-validator-edge-cases.test.ts
│ │ │ ├── expression-validator.test.ts
│ │ │ ├── fixed-collection-validation.test.ts
│ │ │ ├── loop-output-edge-cases.test.ts
│ │ │ ├── n8n-api-client.test.ts
│ │ │ ├── n8n-validation.test.ts
│ │ │ ├── node-similarity-service.test.ts
│ │ │ ├── node-specific-validators.test.ts
│ │ │ ├── operation-similarity-service-comprehensive.test.ts
│ │ │ ├── operation-similarity-service.test.ts
│ │ │ ├── property-dependencies.test.ts
│ │ │ ├── property-filter-edge-cases.test.ts
│ │ │ ├── property-filter.test.ts
│ │ │ ├── resource-similarity-service-comprehensive.test.ts
│ │ │ ├── resource-similarity-service.test.ts
│ │ │ ├── task-templates.test.ts
│ │ │ ├── template-service.test.ts
│ │ │ ├── universal-expression-validator.test.ts
│ │ │ ├── validation-fixes.test.ts
│ │ │ ├── workflow-auto-fixer.test.ts
│ │ │ ├── workflow-diff-engine.test.ts
│ │ │ ├── workflow-fixed-collection-validation.test.ts
│ │ │ ├── workflow-validator-comprehensive.test.ts
│ │ │ ├── workflow-validator-edge-cases.test.ts
│ │ │ ├── workflow-validator-error-outputs.test.ts
│ │ │ ├── workflow-validator-expression-format.test.ts
│ │ │ ├── workflow-validator-loops-simple.test.ts
│ │ │ ├── workflow-validator-loops.test.ts
│ │ │ ├── workflow-validator-mocks.test.ts
│ │ │ ├── workflow-validator-performance.test.ts
│ │ │ ├── workflow-validator-with-mocks.test.ts
│ │ │ └── workflow-validator.test.ts
│ │ ├── telemetry
│ │ │ ├── batch-processor.test.ts
│ │ │ ├── config-manager.test.ts
│ │ │ ├── event-tracker.test.ts
│ │ │ ├── event-validator.test.ts
│ │ │ ├── rate-limiter.test.ts
│ │ │ ├── telemetry-error.test.ts
│ │ │ ├── telemetry-manager.test.ts
│ │ │ ├── v2.18.3-fixes-verification.test.ts
│ │ │ └── workflow-sanitizer.test.ts
│ │ ├── templates
│ │ │ ├── batch-processor.test.ts
│ │ │ ├── metadata-generator.test.ts
│ │ │ ├── template-repository-metadata.test.ts
│ │ │ └── template-repository-security.test.ts
│ │ ├── test-env-example.test.ts
│ │ ├── test-infrastructure.test.ts
│ │ ├── types
│ │ │ ├── instance-context-coverage.test.ts
│ │ │ └── instance-context-multi-tenant.test.ts
│ │ ├── utils
│ │ │ ├── auth-timing-safe.test.ts
│ │ │ ├── cache-utils.test.ts
│ │ │ ├── console-manager.test.ts
│ │ │ ├── database-utils.test.ts
│ │ │ ├── fixed-collection-validator.test.ts
│ │ │ ├── n8n-errors.test.ts
│ │ │ ├── node-type-normalizer.test.ts
│ │ │ ├── node-type-utils.test.ts
│ │ │ ├── node-utils.test.ts
│ │ │ ├── simple-cache-memory-leak-fix.test.ts
│ │ │ ├── ssrf-protection.test.ts
│ │ │ └── template-node-resolver.test.ts
│ │ └── validation-fixes.test.ts
│ └── utils
│ ├── assertions.ts
│ ├── builders
│ │ └── workflow.builder.ts
│ ├── data-generators.ts
│ ├── database-utils.ts
│ ├── README.md
│ └── test-helpers.ts
├── thumbnail.png
├── tsconfig.build.json
├── tsconfig.json
├── types
│ ├── mcp.d.ts
│ └── test-env.d.ts
├── verify-telemetry-fix.js
├── versioned-nodes.md
├── vitest.config.benchmark.ts
├── vitest.config.integration.ts
└── vitest.config.ts
```
# Files
--------------------------------------------------------------------------------
/docs/FINAL_AI_VALIDATION_SPEC.md:
--------------------------------------------------------------------------------
```markdown
1 | # Final AI Node Validation Specification
2 |
3 | ## AI Agent Deep Architecture Analysis
4 |
5 | ### 1. Prompt Construction and Message Flow
6 |
7 | The AI Agent node handles user prompts through two distinct modes controlled by `promptType`:
8 |
9 | #### Mode 1: Auto (Connected Chat Trigger)
10 | ```typescript
11 | {
12 | "promptType": "auto",
13 | "text": "={{ $json.chatInput }}" // Default value
14 | }
15 | ```
16 | - **Behavior**: Expects input from Chat Trigger node via `main` connection
17 | - **User Message Source**: `$json.chatInput` from Chat Trigger
18 | - **Use Case**: Interactive chatbots with ongoing conversations
19 | - **Validation**: MUST have Chat Trigger → AI Agent main connection
20 |
21 | #### Mode 2: Define Below
22 | ```typescript
23 | {
24 | "promptType": "define",
25 | "text": "Your custom prompt or ={{ $json.someField }}"
26 | }
27 | ```
28 | - **Behavior**: User message defined in node parameters
29 | - **User Message Source**: Static text or expression from previous node
30 | - **Use Case**: Automated processing, data transformations, batch operations
31 | - **Validation**: Text field is REQUIRED when promptType="define"
32 |
33 | **Real-World Examples**:
34 | ```typescript
35 | // Example 1: WhatsApp message processing
36 | {
37 | "promptType": "define",
38 | "text": "={{ $json.messages[0].text.body }}"
39 | }
40 |
41 | // Example 2: Content generation with structured input
42 | {
43 | "promptType": "define",
44 | "text": "Generate a creative concept involving:\n\n[[\nA solid, hard material..."
45 | }
46 | ```
47 |
48 | ### 2. System Message: The Agent's Core Instructions
49 |
50 | System messages define the agent's **role, capabilities, constraints, and output format**. This is the most critical parameter for AI Agent behavior.
51 |
52 | #### System Message Structure Pattern:
53 | ```typescript
54 | {
55 | "options": {
56 | "systemMessage": `
57 | **Role:**
58 | [Define agent's persona and primary function]
59 |
60 | **Capabilities:**
61 | [List what the agent can do, tools it has access to]
62 |
63 | **Rules:**
64 | [Constraints, formatting requirements, behavior guidelines]
65 |
66 | **Output Format:**
67 | [Specific structure for responses]
68 |
69 | **Process:**
70 | [Step-by-step execution flow]
71 | `
72 | }
73 | }
74 | ```
75 |
76 | #### Real-World System Message Examples:
77 |
78 | **Example 1: Database Assistant** (Template 2985)
79 | ```typescript
80 | {
81 | "options": {
82 | "systemMessage": "You are an assistant working for a company who sells Yamaha Powered Loudspeakers and helping the user navigate the product catalog for the year 2024. Your goal is not to facilitate a sale but if the user enquires, direct them to the appropriate website, url or contact information.\n\nDo your best to answer any questions factually. If you don't know the answer or unable to obtain the information from the datastore, then tell the user so."
83 | }
84 | }
85 | ```
86 | **Pattern**: Clear role, specific domain, behavior constraints
87 |
88 | **Example 2: Content Generator with Output Format** (Template 214907)
89 | ```typescript
90 | {
91 | "options": {
92 | "systemMessage": "**Role:** \nYou are an AI designed to generate **one immersive, realistic idea** based on a user-provided topic. Your output must be formatted as a **single-line JSON array** and follow the rules below exactly.\n\n### RULES\n\n1. **Number of ideas** \n - Return **only one idea**.\n\n2. **Topic** \n - The user will provide a keyword (e.g., \"glass cutting ASMR\").\n\n3. **Idea** \n - Maximum 13 words. \n - Describe a viral-worthy, original, or surreal moment.\n\n4. **Caption** \n - Short, punchy, viral-friendly. \n - Include **one emoji**. \n - Exactly **12 hashtags** in this order: \n 1. 4 topic-relevant hashtags \n 2. 4 all-time most popular hashtags \n 3. 4 currently trending hashtags\n\n### OUTPUT FORMAT (single-line JSON array)\n\n```json\n[\n {\n \"Caption\": \"...\",\n \"Idea\": \"...\",\n \"Environment\": \"...\",\n \"Sound\": \"...\",\n \"Status\": \"for production\"\n }\n]\n```"
93 | }
94 | }
95 | ```
96 | **Pattern**: Detailed rules, strict output format (JSON), validation constraints
97 |
98 | **Example 3: Multi-Step Process Agent** (Template 5296)
99 | ```typescript
100 | {
101 | "options": {
102 | "systemMessage": "You are an assistant that helps YouTube creators uncover what topics are trending in a given niche over the past two days.\n\n1. Niche Check\n\nIf the user has not yet specified a niche, respond with a short list of 5 popular niches and ask them to choose one.\n\n2. Trend Search\n\nOnce you know the niche, choose up to three distinct search queries that reflect different angles of that niche.\n\nFor each query, call the youtube_search tool to retrieve videos published in the last 2 days.\n\n3. Data Handling\n\nThe tool returns multiple JSON entries, each with fields:\n \"video_id\": \"...\", \n \"view_count\": ..., \n ...\n\n4. Insight Generation\n\nAggregate results across all queries. Don't discuss individual videos; instead, synthesize overall patterns:\n\n5. Final Output\n\nSummarize the top 2–3 trending topics or formats in this niche over the last 48 hours."
103 | }
104 | }
105 | ```
106 | **Pattern**: Step-by-step process flow, tool usage instructions, aggregation logic
107 |
108 | #### System Message Best Practices:
109 | 1. **Always define the role** - What is the agent's purpose?
110 | 2. **Specify constraints** - What should it NOT do?
111 | 3. **Define output format** - JSON, markdown, specific structure?
112 | 4. **Include tool usage guidance** - When to call which tools?
113 | 5. **Add validation rules** - What makes a valid response?
114 |
115 | ### 3. Fallback Models: Reliability Enhancement
116 |
117 | Fallback models provide automatic failover when the primary LLM fails (rate limits, errors, downtime).
118 |
119 | #### Configuration:
120 | ```typescript
121 | {
122 | "needsFallback": true // Default: false, only in version 2.1+
123 | }
124 | ```
125 |
126 | #### Connection Pattern:
127 | ```
128 | [Primary LLM] --ai_languageModel[0]--> [AI Agent]
129 | [Fallback LLM] --ai_languageModel[1]--> [AI Agent]
130 | ```
131 |
132 | #### Validation Rules:
133 | ```typescript
134 | if (node.parameters.needsFallback === true) {
135 | const languageModelConnections = reverseConnections
136 | .get(node.name)
137 | .filter(c => c.type === 'ai_languageModel');
138 |
139 | if (languageModelConnections.length < 2) {
140 | issues.push({
141 | severity: 'error',
142 | message: `AI Agent "${node.name}" has needsFallback=true but only ${languageModelConnections.length} language model connection(s). Connect a second language model as fallback.`
143 | });
144 | }
145 | } else {
146 | // Normal case: exactly 1 language model required
147 | const languageModelConnections = reverseConnections
148 | .get(node.name)
149 | .filter(c => c.type === 'ai_languageModel');
150 |
151 | if (languageModelConnections.length !== 1) {
152 | issues.push({
153 | severity: 'error',
154 | message: `AI Agent "${node.name}" requires exactly 1 language model connection, found ${languageModelConnections.length}.`
155 | });
156 | }
157 | }
158 | ```
159 |
160 | #### When to Use Fallback Models:
161 | - **Production systems** with high availability requirements
162 | - **Multi-LLM strategies** (e.g., GPT-4 primary, Claude fallback)
163 | - **Cost optimization** (expensive primary, cheaper fallback)
164 | - **Rate limit mitigation** (automatic switch on 429 errors)
165 |
166 | ### 4. Output Parsers: Structured Data Enforcement
167 |
168 | Output parsers ensure the LLM returns data in a specific, machine-readable format (JSON, XML, structured text).
169 |
170 | #### Configuration:
171 | ```typescript
172 | {
173 | "hasOutputParser": true // Default: false
174 | }
175 | ```
176 |
177 | #### Connection Pattern:
178 | ```
179 | [Output Parser] --ai_outputParser--> [AI Agent]
180 | ```
181 |
182 | #### Available Output Parsers:
183 | - **Structured Output Parser**: JSON with strict schema validation
184 | - **Auto-fixing Output Parser**: Attempts to fix malformed JSON
185 | - **Markdown Output Parser**: Structured markdown
186 | - **Custom Output Parser**: User-defined format
187 |
188 | #### Validation Rules:
189 | ```typescript
190 | if (node.parameters.hasOutputParser === true) {
191 | const outputParserConnections = reverseConnections
192 | .get(node.name)
193 | .filter(c => c.type === 'ai_outputParser');
194 |
195 | if (outputParserConnections.length === 0) {
196 | issues.push({
197 | severity: 'error',
198 | message: `AI Agent "${node.name}" has hasOutputParser=true but no ai_outputParser connection. Connect an Output Parser node.`
199 | });
200 | } else if (outputParserConnections.length > 1) {
201 | issues.push({
202 | severity: 'warning',
203 | message: `AI Agent "${node.name}" has ${outputParserConnections.length} output parser connections. Only the first will be used.`
204 | });
205 | }
206 | }
207 | ```
208 |
209 | #### Real-World Usage (Template 214907):
210 | ```typescript
211 | {
212 | "hasOutputParser": true,
213 | "options": {
214 | "systemMessage": "... Your output must be formatted as a **single-line JSON array** ..."
215 | }
216 | }
217 | // Connected to Structured Output Parser with JSON schema
218 | ```
219 |
220 | **Pattern**: System message defines format rules, output parser enforces schema validation
221 |
222 | ### 5. Additional Options Collection
223 |
224 | The `options` collection contains advanced configuration:
225 |
226 | ```typescript
227 | {
228 | "options": {
229 | "systemMessage": string, // Agent's core instructions
230 | "maxIterations": number, // Max tool call loops (default: 10)
231 | "returnIntermediateSteps": boolean, // Include reasoning steps in output
232 | "passthroughBinaryImages": boolean, // Handle binary image data
233 | "batching": object // Batch processing config
234 | }
235 | }
236 | ```
237 |
238 | #### maxIterations
239 | ```typescript
240 | {
241 | "options": {
242 | "maxIterations": 15 // Default: 10
243 | }
244 | }
245 | ```
246 | - **Purpose**: Prevents infinite tool-calling loops
247 | - **Use Case**: Complex multi-tool workflows (e.g., research → search → summarize → verify)
248 | - **Validation**: Should be reasonable (1-50), warn if > 20
249 |
250 | #### returnIntermediateSteps
251 | ```typescript
252 | {
253 | "options": {
254 | "returnIntermediateSteps": true // Default: false
255 | }
256 | }
257 | ```
258 | - **Purpose**: Returns step-by-step reasoning and tool calls
259 | - **Use Case**: Debugging, transparency, audit trails
260 | - **Output**: Includes intermediate thoughts, tool inputs/outputs
261 | - **Performance**: Increases token usage and response time
262 |
263 | #### passthroughBinaryImages
264 | ```typescript
265 | {
266 | "options": {
267 | "passthroughBinaryImages": true // Default: false
268 | }
269 | }
270 | ```
271 | - **Purpose**: Enables vision models to process images
272 | - **Use Case**: Image analysis, OCR, visual question answering
273 | - **Requirement**: LLM must support vision (GPT-4 Vision, Claude 3 Opus)
274 |
275 | #### batching
276 | ```typescript
277 | {
278 | "options": {
279 | "batching": {
280 | "enabled": true,
281 | "batchSize": 10
282 | }
283 | }
284 | }
285 | ```
286 | - **Purpose**: Process multiple inputs in parallel
287 | - **Use Case**: Bulk data processing, batch API calls
288 | - **Optimization**: Reduces total execution time
289 |
290 | ### 6. Version Differences and Migration
291 |
292 | #### Version 1.x (Legacy)
293 | ```typescript
294 | {
295 | "typeVersion": 1.7,
296 | "parameters": {
297 | "promptType": "auto",
298 | "text": "...",
299 | "options": {
300 | "systemMessage": "..."
301 | }
302 | }
303 | }
304 | ```
305 | - No `needsFallback` option
306 | - No `hasOutputParser` option
307 | - Limited options collection
308 |
309 | #### Version 2.1+ (Current)
310 | ```typescript
311 | {
312 | "typeVersion": 2.2,
313 | "parameters": {
314 | "promptType": "auto",
315 | "text": "...",
316 | "hasOutputParser": true,
317 | "needsFallback": true,
318 | "options": {
319 | "systemMessage": "...",
320 | "maxIterations": 15,
321 | "returnIntermediateSteps": true,
322 | "passthroughBinaryImages": true,
323 | "batching": {...}
324 | }
325 | }
326 | }
327 | ```
328 | - Added `needsFallback` flag
329 | - Added `hasOutputParser` flag
330 | - Expanded options collection
331 | - Better streaming support
332 |
333 | #### Validation Considerations:
334 | ```typescript
335 | function validateAIAgentVersion(node: WorkflowNode): ValidationIssue[] {
336 | const issues: ValidationIssue[] = [];
337 |
338 | if (node.parameters.needsFallback && node.typeVersion < 2.1) {
339 | issues.push({
340 | severity: 'error',
341 | message: `AI Agent "${node.name}" uses needsFallback but typeVersion ${node.typeVersion} does not support it. Upgrade to version 2.1+.`
342 | });
343 | }
344 |
345 | return issues;
346 | }
347 | ```
348 |
349 | ### 7. Complete AI Agent Validation Specification
350 |
351 | ```typescript
352 | interface AIAgentRequirements {
353 | // Required Properties
354 | text: {
355 | required: true;
356 | default: "={{ $json.chatInput }}" | ""; // Based on promptType
357 | validation: "Must not be empty when promptType='define'";
358 | };
359 |
360 | // Connection Requirements
361 | connections: {
362 | ai_languageModel: {
363 | min: 1;
364 | max: 1; // or 2 if needsFallback=true
365 | required: true;
366 | };
367 | ai_memory: {
368 | min: 0;
369 | max: 1;
370 | optional: true;
371 | };
372 | ai_tool: {
373 | min: 0;
374 | max: Infinity;
375 | optional: true;
376 | };
377 | ai_outputParser: {
378 | min: 0;
379 | max: 1;
380 | optional: true;
381 | requiredIf: "hasOutputParser === true";
382 | };
383 | main: {
384 | input: {
385 | typical: 1;
386 | source: "Chat Trigger or other node";
387 | requiredIf: "promptType === 'auto'";
388 | };
389 | output: {
390 | allowed: true;
391 | forbiddenIf: "upstream Chat Trigger has responseMode='streaming'";
392 | };
393 | };
394 | };
395 |
396 | // Optional Enhancements
397 | options: {
398 | systemMessage: {
399 | recommended: true;
400 | purpose: "Define agent role, capabilities, constraints";
401 | validation: "Should be clear, specific, include tool usage instructions";
402 | };
403 | maxIterations: {
404 | default: 10;
405 | range: [1, 50];
406 | warning: "Values > 20 may cause long execution times";
407 | };
408 | returnIntermediateSteps: {
409 | default: false;
410 | impact: "Increases output size and token usage";
411 | };
412 | passthroughBinaryImages: {
413 | default: false;
414 | requires: "LLM with vision capabilities";
415 | };
416 | };
417 |
418 | // Version-Specific Features
419 | features: {
420 | needsFallback: {
421 | sinceVersion: 2.1;
422 | requiresConnections: 2; // 2x ai_languageModel
423 | };
424 | hasOutputParser: {
425 | sinceVersion: 2.0;
426 | requiresConnection: "ai_outputParser";
427 | };
428 | };
429 | }
430 | ```
431 |
432 | ### 8. Improving MCP Tool Responses for AI Agent
433 |
434 | Based on this analysis, MCP tools should return:
435 |
436 | #### For `get_node_info` / `get_node_essentials`:
437 | ```typescript
438 | {
439 | "essentials": {
440 | // Highlight prompt configuration
441 | "promptConfiguration": {
442 | "promptType": "auto (Chat Trigger) or define (Custom)",
443 | "textField": "REQUIRED when promptType='define'",
444 | "defaultValue": "={{ $json.chatInput }}"
445 | },
446 |
447 | // Emphasize system message importance
448 | "systemMessage": {
449 | "location": "options.systemMessage",
450 | "importance": "CRITICAL - defines agent behavior",
451 | "bestPractices": [
452 | "Define clear role and purpose",
453 | "Specify output format requirements",
454 | "Include tool usage instructions",
455 | "Add constraints and validation rules"
456 | ]
457 | },
458 |
459 | // Document fallback feature
460 | "fallbackModels": {
461 | "flag": "needsFallback",
462 | "sinceVersion": 2.1,
463 | "requires": "2 ai_languageModel connections",
464 | "useCase": "High-availability production systems"
465 | },
466 |
467 | // Document output parser integration
468 | "outputParsers": {
469 | "flag": "hasOutputParser",
470 | "requires": "1 ai_outputParser connection",
471 | "useCase": "Structured JSON/XML output"
472 | }
473 | }
474 | }
475 | ```
476 |
477 | #### For `search_nodes` with query "AI Agent":
478 | ```typescript
479 | {
480 | "results": [
481 | {
482 | "node": "AI Agent",
483 | "keyFeatures": [
484 | "Multi-tool orchestration",
485 | "Conversation memory integration",
486 | "System message for role definition",
487 | "Fallback model support (v2.1+)",
488 | "Output format enforcement via parsers"
489 | ],
490 | "criticalConnections": [
491 | "ai_languageModel (REQUIRED, 1-2 connections)",
492 | "ai_memory (OPTIONAL, 0-1 connections)",
493 | "ai_tool (OPTIONAL, 0-N connections)",
494 | "ai_outputParser (OPTIONAL, 0-1 connections)"
495 | ],
496 | "commonPatterns": [
497 | "Chat Trigger → AI Agent (streaming chatbots)",
498 | "AI Agent + Memory + Tools (conversational agents)",
499 | "AI Agent + Output Parser (structured data extraction)"
500 | ]
501 | }
502 | ]
503 | }
504 | ```
505 |
506 | #### For `get_node_documentation`:
507 | ```markdown
508 | # AI Agent
509 |
510 | ## Overview
511 | The AI Agent node orchestrates complex workflows by combining language models, tools, and memory to solve multi-step problems.
512 |
513 | ## Critical Configuration
514 |
515 | ### 1. User Prompt
516 | - **promptType**: "auto" (from Chat Trigger) or "define" (custom)
517 | - **text**: User message (REQUIRED when promptType="define")
518 |
519 | ### 2. System Message (CRITICAL)
520 | - **Location**: options.systemMessage
521 | - **Purpose**: Defines agent's role, capabilities, constraints
522 | - **Best Practices**:
523 | - Start with role definition
524 | - List available tools and when to use them
525 | - Specify output format requirements
526 | - Add behavioral constraints
527 |
528 | ### 3. Fallback Models (v2.1+)
529 | - **Flag**: needsFallback
530 | - **Requires**: 2 ai_languageModel connections
531 | - **Use Case**: Production reliability, rate limit handling
532 |
533 | ### 4. Output Parsers
534 | - **Flag**: hasOutputParser
535 | - **Requires**: 1 ai_outputParser connection
536 | - **Use Case**: JSON/XML structured output validation
537 |
538 | ## Connection Requirements
539 | - **ai_languageModel**: REQUIRED (1 or 2 if fallback enabled)
540 | - **ai_memory**: OPTIONAL (conversation context)
541 | - **ai_tool**: OPTIONAL (external capabilities)
542 | - **ai_outputParser**: OPTIONAL (output formatting)
543 |
544 | ## Common Mistakes
545 | 1. Missing system message → Generic, unhelpful responses
546 | 2. Too many maxIterations → Infinite loops, high costs
547 | 3. hasOutputParser=true but no parser connected → Runtime error
548 | 4. Streaming mode + main output → Response lost
549 | ```
550 |
551 | ## Critical Architecture: Connection Flow Direction
552 |
553 | ### CRITICAL INSIGHT: AI Connections Flow TO Consumers
554 |
555 | Unlike standard n8n nodes where data flows FROM source TO target via `main` connections, **AI-specific connections flow TO the AI Agent/Chain nodes**, not from them:
556 |
557 | ```
558 | Standard n8n pattern:
559 | [HTTP Request] --main--> [Set] --main--> [Slack]
560 |
561 | AI pattern (REVERSED):
562 | [Language Model] --ai_languageModel--> [AI Agent]
563 | [Memory Buffer] --ai_memory--------> [AI Agent]
564 | [Tool Node] --ai_tool----------> [AI Agent]
565 | [Chat Trigger] --main-------------> [AI Agent]
566 | [AI Agent] --main (optional)--> [Next Node]
567 | ```
568 |
569 | **Why This Matters for Validation:**
570 | - Standard validation checks: `workflow.connections[sourceName][outputType]`
571 | - AI validation needs: **Reverse connection map** to check what connects TO each node
572 | - Must build: `Map<targetNodeName, Connection[]>` to validate AI nodes
573 |
574 | **Real Example from Template #2985:**
575 | ```json
576 | {
577 | "connections": {
578 | "Groq Chat Model": {
579 | "ai_languageModel": [[{
580 | "node": "AI Agent",
581 | "type": "ai_languageModel",
582 | "index": 0
583 | }]]
584 | },
585 | "Chat History": {
586 | "ai_memory": [[{
587 | "node": "AI Agent",
588 | "type": "ai_memory",
589 | "index": 0
590 | }]]
591 | }
592 | }
593 | }
594 | ```
595 |
596 | Notice: Connections are defined in **source nodes** but flow **TO the AI Agent**.
597 |
598 | ## Complete AI Tool Ecosystem
599 |
600 | We have **269 nodes total** that can be used as AI tools in our database:
601 | - **21 nodes** from `@n8n/n8n-nodes-langchain` (AI components)
602 | - **248 nodes** from `n8n-nodes-base` (regular nodes)
603 |
604 | ### Purpose-Built AI Tool Sub-Nodes
605 |
606 | These are the **13 specialized tool nodes** from `@n8n/n8n-nodes-langchain` designed specifically for AI Agent tool connections:
607 |
608 | | Node Type | Display Name | Purpose | Special Requirements |
609 | |-----------|--------------|---------|---------------------|
610 | | `toolExecutor` | Tool Executor | Execute tools without AI Agent | No AI Agent connection needed |
611 | | `agentTool` | AI Agent Tool | AI Agent packaged as a tool | Must have ai_languageModel |
612 | | `toolWorkflow` | Call n8n Sub-Workflow Tool | Execute sub-workflows | Sub-workflow must exist |
613 | | `toolCode` | Code Tool | JavaScript/Python execution | Should have input schema |
614 | | `toolHttpRequest` | HTTP Request Tool | HTTP API calls | Should have placeholder definitions |
615 | | `mcpClientTool` | MCP Client Tool | Connect MCP Server tools | Requires MCP server config |
616 | | `toolThink` | Think Tool | AI reflection/thinking | No special requirements |
617 | | `toolVectorStore` | Vector Store Q&A Tool | RAG from vector store | Requires ai_vectorStore + ai_embedding chain |
618 | | `toolCalculator` | Calculator | Arithmetic operations | No special requirements |
619 | | `toolSearXng` | SearXNG | SearXNG search | Requires credentials |
620 | | `toolSerpApi` | SerpApi (Google Search) | Google search via SerpAPI | Requires credentials |
621 | | `toolWikipedia` | Wikipedia | Wikipedia search | No special requirements |
622 | | `toolWolframAlpha` | Wolfram\|Alpha | Computational queries | Requires credentials |
623 |
624 | ### Regular n8n Nodes Usable as Tools
625 |
626 | **248 regular nodes** from `n8n-nodes-base` can be used as AI tools when `N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true`:
627 |
628 | **Examples include**:
629 | - Action Network, ActiveCampaign, Adalo, Affinity, Agile CRM
630 | - Airtable, Airtop, AMQP Sender, Asana, Autopilot
631 | - AWS services (Lambda, SES, SNS, Textract, Transcribe)
632 | - Communication (Slack, Discord, Telegram, WhatsApp, Email)
633 | - Databases (MySQL, PostgreSQL, MongoDB, Redis)
634 | - Cloud storage (Google Drive, Dropbox, S3)
635 | - Project management (Jira, Trello, ClickUp, Asana)
636 | - CRM (Salesforce, HubSpot, Pipedrive)
637 | - And 200+ more...
638 |
639 | **Generic Tool Validation** (applies to all 248 nodes):
640 | ```typescript
641 | interface RegularNodeAsToolValidation {
642 | connection: 'ai_tool'; // MUST connect via ai_tool output
643 | description: {
644 | // Tool description helps LLM decide when to use it
645 | source: 'node.parameters.toolDescription' | 'node.parameters.description';
646 | recommended: true;
647 | };
648 | credentials: {
649 | // Credentials are handled by n8n, not exposed to LLM
650 | validated: boolean;
651 | };
652 | parameters: {
653 | // All parameters should be valid for the node's operation
654 | validated: boolean;
655 | };
656 | }
657 | ```
658 |
659 | **When to warn**: Regular node used as tool should have:
660 | 1. Connection to AI Agent via `ai_tool` output
661 | 2. Valid credentials configured (if required)
662 | 3. Proper operation/resource selected
663 | 4. Optional but recommended: Custom tool description
664 |
665 | ## Connection Type Validation Matrix
666 |
667 | ### AI Agent (@n8n/n8n-nodes-langchain.agent)
668 |
669 | | Connection Type | Cardinality | Direction | Validation |
670 | |----------------|-------------|-----------|------------|
671 | | `ai_languageModel` | **REQUIRED** (1 or 2) | LLM → Agent | Exactly 1 (or 2 if needsFallback=true) |
672 | | `ai_memory` | Optional (0-1) | Memory → Agent | 0 or 1 allowed |
673 | | `ai_tool` | Optional (0-N) | Tool → Agent | Any number allowed |
674 | | `ai_outputParser` | Optional (0-1) | Parser → Agent | 0 or 1 allowed (required if hasOutputParser=true) |
675 | | `main` (input) | Typical (1) | Trigger → Agent | Usually from Chat Trigger |
676 | | `main` (output) | Conditional | Agent → Node | FORBIDDEN if streaming mode |
677 |
678 | **Validation Rules**:
679 |
680 | 1. **Language Model Requirement**:
681 | ```typescript
682 | if (node.parameters.needsFallback === true) {
683 | // MUST have exactly 2 ai_languageModel connections
684 | if (languageModelCount !== 2) {
685 | ERROR: "AI Agent with needsFallback=true requires 2 language models"
686 | }
687 | } else {
688 | // MUST have exactly 1 ai_languageModel connection
689 | if (languageModelCount !== 1) {
690 | ERROR: "AI Agent requires exactly 1 language model"
691 | }
692 | }
693 | ```
694 |
695 | 2. **Output Parser Requirement**:
696 | ```typescript
697 | if (node.parameters.hasOutputParser === true) {
698 | // MUST have exactly 1 ai_outputParser connection
699 | if (outputParserCount === 0) {
700 | ERROR: "AI Agent with hasOutputParser=true requires an output parser connection"
701 | }
702 | }
703 | ```
704 |
705 | 3. **Streaming Mode Rule**:
706 | ```typescript
707 | IF (Chat Trigger → AI Agent with responseMode="streaming")
708 | THEN (AI Agent MUST NOT have main output connections)
709 | ```
710 |
711 | 4. **Prompt Type Rule**:
712 | ```typescript
713 | if (node.parameters.promptType === "auto") {
714 | // Should have Chat Trigger as input
715 | if (!hasChatTriggerInput) {
716 | WARNING: "AI Agent with promptType='auto' should receive input from Chat Trigger"
717 | }
718 | }
719 |
720 | if (node.parameters.promptType === "define") {
721 | // Text field must not be empty
722 | if (!node.parameters.text || node.parameters.text.trim() === "") {
723 | ERROR: "AI Agent with promptType='define' must have non-empty text field"
724 | }
725 | }
726 | ```
727 |
728 | ### Basic LLM Chain (@n8n/n8n-nodes-langchain.chainLlm)
729 |
730 | | Connection Type | Cardinality | Direction | Validation |
731 | |----------------|-------------|-----------|------------|
732 | | `ai_languageModel` | **REQUIRED** (1) | LLM → Chain | MUST have exactly 1 |
733 | | `ai_outputParser` | Optional (0-1) | Parser → Chain | 0 or 1 allowed |
734 | | `ai_memory` | **FORBIDDEN** | - | MUST NOT have |
735 | | `ai_tool` | **FORBIDDEN** | - | MUST NOT have |
736 |
737 | ### Vector Store Tool (@n8n/n8n-nodes-langchain.toolVectorStore)
738 |
739 | | Connection Type | Cardinality | Direction | Validation |
740 | |----------------|-------------|-----------|------------|
741 | | `ai_vectorStore` | **REQUIRED** (1) | VectorStore → Tool | MUST have exactly 1 |
742 | | `ai_tool` (output) | Typical (1) | Tool → Agent | Should connect to AI Agent |
743 |
744 | **Chain Validation**:
745 | ```
746 | Vector Store Tool
747 | ← ai_vectorStore ← Vector Store
748 | ← ai_embedding ← Embeddings Model
749 | ← ai_document ← Document Loader
750 | ← ai_textSplitter ← Text Splitter (optional)
751 | ```
752 |
753 | ### Chat Trigger (@n8n/n8n-nodes-langchain.chatTrigger)
754 |
755 | **Purpose**: Trigger node specifically designed for AI chatbot workflows. Provides a web interface for chat interactions.
756 |
757 | **Key Characteristics**:
758 | - **Is Trigger**: Yes (starts workflow)
759 | - **Is Webhook**: Yes (provides HTTP endpoint)
760 | - **Output Type**: `main` (connects to AI Agent or workflow logic)
761 |
762 | **Unique Features**:
763 | - Hosted chat UI (`mode: "hostedChat"`)
764 | - Embedded chat widget (`mode: "webhook"`)
765 | - File upload support
766 | - Session management
767 | - Streaming response capability
768 | - Custom CSS styling
769 |
770 | | Property | Values | Impact on Validation |
771 | |----------|--------|---------------------|
772 | | `responseMode` | "streaming" | AI Agent must NOT have main output (response streams back through trigger) |
773 | | | "lastNode" | Normal workflow allowed (data from last executed node returned) |
774 | | | "responseNode" | Must have Respond to Webhook node in workflow |
775 | | | "responseNodes" | Must have Response nodes configured |
776 | | `mode` | "hostedChat" | Provides n8n-hosted chat interface |
777 | | | "webhook" | Embeddable chat widget |
778 |
779 | **Validation Requirements**:
780 | ```typescript
781 | function validateChatTrigger(
782 | node: WorkflowNode,
783 | workflow: WorkflowJson,
784 | result: WorkflowValidationResult
785 | ): void {
786 | const connections = workflow.connections[node.name];
787 |
788 | // 1. Check has downstream connections
789 | if (!connections?.main || connections.main.flat().filter(c => c).length === 0) {
790 | result.errors.push({
791 | type: 'error',
792 | nodeId: node.id,
793 | nodeName: node.name,
794 | message: `Chat Trigger "${node.name}" has no downstream connections. Connect it to an AI Agent or workflow logic.`
795 | });
796 | return;
797 | }
798 |
799 | // 2. Check responseMode compatibility
800 | const responseMode = node.parameters?.options?.responseMode || 'lastNode';
801 | const firstConnection = connections.main[0]?.[0];
802 |
803 | if (firstConnection) {
804 | const targetNode = workflow.nodes.find(n => n.name === firstConnection.node);
805 | const targetType = targetNode ? NodeTypeNormalizer.normalizeToFullForm(targetNode.type) : '';
806 |
807 | if (responseMode === 'streaming') {
808 | // Must connect to streaming-capable node
809 | if (targetType !== '@n8n/n8n-nodes-langchain.agent') {
810 | result.errors.push({
811 | type: 'error',
812 | nodeId: node.id,
813 | nodeName: node.name,
814 | message: `Chat Trigger "${node.name}" has responseMode="streaming" but does not connect to an AI Agent. Only AI Agent supports streaming responses.`
815 | });
816 | } else {
817 | // Check AI Agent has enableStreaming option
818 | const enableStreaming = targetNode?.parameters?.options?.enableStreaming;
819 | if (enableStreaming === false) {
820 | result.warnings.push({
821 | type: 'warning',
822 | nodeId: targetNode.id,
823 | nodeName: targetNode.name,
824 | message: `AI Agent "${targetNode.name}" has enableStreaming=false but Chat Trigger uses responseMode="streaming". Enable streaming in the AI Agent options.`
825 | });
826 | }
827 |
828 | // CRITICAL: Check AI Agent has NO main output
829 | const agentMainOutput = workflow.connections[targetNode.name]?.main;
830 | if (agentMainOutput && agentMainOutput.flat().some(c => c)) {
831 | result.errors.push({
832 | type: 'error',
833 | nodeId: targetNode.id,
834 | nodeName: targetNode.name,
835 | message: `AI Agent "${targetNode.name}" is connected from Chat Trigger with responseMode="streaming". It must NOT have outgoing main connections. The response streams back through the Chat Trigger.`
836 | });
837 | }
838 | }
839 | }
840 |
841 | if (responseMode === 'responseNode') {
842 | // Must have Respond to Webhook in workflow
843 | const hasRespondNode = workflow.nodes.some(n =>
844 | n.type.toLowerCase().includes('respondtowebhook')
845 | );
846 | if (!hasRespondNode) {
847 | result.errors.push({
848 | type: 'error',
849 | nodeId: node.id,
850 | nodeName: node.name,
851 | message: `Chat Trigger "${node.name}" has responseMode="responseNode" but no "Respond to Webhook" node found in workflow.`
852 | });
853 | }
854 | }
855 | }
856 |
857 | // 3. Recommend connecting to AI nodes
858 | const downstreamNodes = connections.main.flat()
859 | .map(c => c?.node)
860 | .filter(Boolean) || [];
861 |
862 | const hasAINode = downstreamNodes.some(nodeName => {
863 | const targetNode = workflow.nodes.find(n => n.name === nodeName);
864 | return targetNode && (
865 | targetNode.type.includes('agent') ||
866 | targetNode.type.includes('chainLlm')
867 | );
868 | });
869 |
870 | if (!hasAINode) {
871 | result.warnings.push({
872 | type: 'warning',
873 | nodeId: node.id,
874 | nodeName: node.name,
875 | message: `Chat Trigger "${node.name}" is not connected to an AI Agent or LLM Chain. Consider connecting to an AI node for chat functionality.`
876 | });
877 | }
878 | }
879 | ```
880 |
881 | ## Tool-Specific Validation Rules
882 |
883 | ### 1. HTTP Request Tool (`toolHttpRequest`)
884 |
885 | **Purpose**: Makes HTTP API requests with LLM-filled parameters, allowing AI agents to interact with external REST APIs dynamically.
886 |
887 | **Configuration Options**:
888 | - `toolDescription`: Description for LLM (REQUIRED)
889 | - `method`: HTTP method - GET, POST, PUT, DELETE, PATCH (default: GET)
890 | - `url`: API endpoint URL (REQUIRED, can contain {placeholders})
891 | - `authentication`: None, Predefined Credential, Generic Credential
892 | - `placeholderDefinitions`: Definitions for {placeholders} in URL/body/headers/query
893 | - `sendQuery`: Whether to send query parameters
894 | - `queryParameters`: Query string parameters (can contain {placeholders})
895 | - `sendHeaders`: Whether to send custom headers
896 | - `headerParameters`: HTTP headers (can contain {placeholders})
897 | - `sendBody`: Whether to send request body
898 | - `jsonBody`: Request body JSON (can contain {placeholders})
899 | - `options`: Advanced options (response optimization, etc.)
900 |
901 | **Placeholder System**:
902 | LLM dynamically fills `{placeholder}` values in URL, query, headers, and body based on user input.
903 |
904 | **Critical Requirements**:
905 | 1. Every `{placeholder}` must be defined in `placeholderDefinitions`
906 | 2. Placeholder names must match exactly (case-sensitive)
907 | 3. Tool description should explain what API it accesses
908 |
909 | ```typescript
910 | function validateHTTPRequestTool(node: WorkflowNode): ValidationIssue[] {
911 | const issues: ValidationIssue[] = [];
912 |
913 | // 1. Check for tool description (REQUIRED)
914 | if (!node.parameters.toolDescription) {
915 | issues.push({
916 | severity: 'error',
917 | message: `HTTP Request Tool "${node.name}" has no toolDescription. Add one to help the LLM know when to use this tool.`
918 | });
919 | }
920 |
921 | // 2. Check for URL (REQUIRED)
922 | if (!node.parameters.url) {
923 | issues.push({
924 | severity: 'error',
925 | message: `HTTP Request Tool "${node.name}" has no URL. Provide the API endpoint URL.`
926 | });
927 | }
928 |
929 | // 3. Validate placeholders
930 | const hasPlaceholders =
931 | node.parameters.url?.includes('{') ||
932 | node.parameters.jsonBody?.includes('{') ||
933 | node.parameters.queryParameters?.includes('{') ||
934 | node.parameters.headerParameters?.includes('{');
935 |
936 | if (hasPlaceholders) {
937 | const definitions = node.parameters.placeholderDefinitions?.values || [];
938 | if (definitions.length === 0) {
939 | issues.push({
940 | severity: 'error',
941 | message: `HTTP Request Tool "${node.name}" uses placeholders but has no placeholderDefinitions. Define all placeholders.`
942 | });
943 | }
944 |
945 | // Extract all placeholders from all fields
946 | const allText = `${node.parameters.url || ''} ${JSON.stringify(node.parameters.jsonBody || '')} ${JSON.stringify(node.parameters.queryParameters || '')} ${JSON.stringify(node.parameters.headerParameters || '')}`;
947 | const placeholderRegex = /\{([^}]+)\}/g;
948 | const placeholders = new Set<string>();
949 | let match;
950 | while ((match = placeholderRegex.exec(allText)) !== null) {
951 | placeholders.add(match[1]);
952 | }
953 |
954 | // Check each placeholder is defined
955 | const definedNames = new Set(definitions.map((d: any) => d.name));
956 | for (const placeholder of placeholders) {
957 | if (!definedNames.has(placeholder)) {
958 | issues.push({
959 | severity: 'error',
960 | message: `HTTP Request Tool "${node.name}" uses placeholder {${placeholder}} but it is not defined in placeholderDefinitions.`
961 | });
962 | }
963 | }
964 |
965 | // Validate placeholder definitions have required fields
966 | for (const def of definitions) {
967 | if (!def.name) {
968 | issues.push({
969 | severity: 'error',
970 | message: `HTTP Request Tool "${node.name}" has a placeholder definition without a name.`
971 | });
972 | }
973 | if (!def.description) {
974 | issues.push({
975 | severity: 'warning',
976 | message: `HTTP Request Tool "${node.name}" placeholder "${def.name}" has no description. Add one to help the LLM provide correct values.`
977 | });
978 | }
979 | }
980 | }
981 |
982 | // 4. Validate authentication if specified
983 | if (node.parameters.authentication === 'predefinedCredentialType' ||
984 | node.parameters.authentication === 'genericCredentialType') {
985 | if (!node.credentials || Object.keys(node.credentials).length === 0) {
986 | issues.push({
987 | severity: 'error',
988 | message: `HTTP Request Tool "${node.name}" uses authentication but no credentials are configured.`
989 | });
990 | }
991 | }
992 |
993 | // 5. Validate method
994 | const validMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
995 | if (node.parameters.method && !validMethods.includes(node.parameters.method.toUpperCase())) {
996 | issues.push({
997 | severity: 'error',
998 | message: `HTTP Request Tool "${node.name}" has invalid method "${node.parameters.method}". Must be one of: ${validMethods.join(', ')}.`
999 | });
1000 | }
1001 |
1002 | // 6. Validate body for methods that support it
1003 | if (['POST', 'PUT', 'PATCH'].includes(node.parameters.method?.toUpperCase() || 'GET')) {
1004 | if (node.parameters.sendBody && !node.parameters.jsonBody) {
1005 | issues.push({
1006 | severity: 'warning',
1007 | message: `HTTP Request Tool "${node.name}" has sendBody enabled but no jsonBody specified.`
1008 | });
1009 | }
1010 | }
1011 |
1012 | return issues;
1013 | }
1014 | ```
1015 |
1016 | **Validation Examples**:
1017 |
1018 | ✅ **CORRECT - Simple GET Request**:
1019 | ```json
1020 | {
1021 | "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
1022 | "name": "Get User Info",
1023 | "parameters": {
1024 | "toolDescription": "Retrieves user information by user ID",
1025 | "method": "GET",
1026 | "url": "https://api.example.com/users/{userId}",
1027 | "placeholderDefinitions": {
1028 | "values": [
1029 | {
1030 | "name": "userId",
1031 | "description": "The unique identifier for the user",
1032 | "type": "string"
1033 | }
1034 | ]
1035 | }
1036 | }
1037 | }
1038 | ```
1039 |
1040 | ✅ **CORRECT - POST with Body and Headers**:
1041 | ```json
1042 | {
1043 | "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
1044 | "name": "Create Order",
1045 | "parameters": {
1046 | "toolDescription": "Creates a new order with specified items and quantity",
1047 | "method": "POST",
1048 | "url": "https://api.example.com/orders",
1049 | "authentication": "predefinedCredentialType",
1050 | "sendHeaders": true,
1051 | "headerParameters": {
1052 | "Content-Type": "application/json"
1053 | },
1054 | "sendBody": true,
1055 | "jsonBody": {
1056 | "product": "{productId}",
1057 | "quantity": "{quantity}",
1058 | "customer": "{customerId}"
1059 | },
1060 | "placeholderDefinitions": {
1061 | "values": [
1062 | {
1063 | "name": "productId",
1064 | "description": "Product identifier",
1065 | "type": "string"
1066 | },
1067 | {
1068 | "name": "quantity",
1069 | "description": "Number of items to order",
1070 | "type": "number"
1071 | },
1072 | {
1073 | "name": "customerId",
1074 | "description": "Customer ID",
1075 | "type": "string"
1076 | }
1077 | ]
1078 | }
1079 | }
1080 | }
1081 | ```
1082 |
1083 | ❌ **INCORRECT - Missing URL**:
1084 | ```json
1085 | {
1086 | "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
1087 | "parameters": {
1088 | "toolDescription": "Get data",
1089 | "method": "GET"
1090 | // Missing url!
1091 | }
1092 | }
1093 | ```
1094 |
1095 | ❌ **INCORRECT - Placeholder Not Defined**:
1096 | ```json
1097 | {
1098 | "parameters": {
1099 | "toolDescription": "Get user",
1100 | "url": "https://api.example.com/users/{userId}",
1101 | "placeholderDefinitions": {
1102 | "values": [
1103 | {
1104 | "name": "id", // Wrong! URL uses {userId} not {id}
1105 | "description": "User ID",
1106 | "type": "string"
1107 | }
1108 | ]
1109 | }
1110 | }
1111 | }
1112 | ```
1113 |
1114 | ❌ **INCORRECT - Missing Tool Description**:
1115 | ```json
1116 | {
1117 | "parameters": {
1118 | "method": "GET",
1119 | "url": "https://api.example.com/data"
1120 | // Missing toolDescription! LLM won't know when to use this
1121 | }
1122 | }
1123 | ```
1124 |
1125 | ### 2. Code Tool (`toolCode`)
1126 |
1127 | **Purpose**: Executes custom JavaScript or Python code as an AI tool, allowing the LLM to perform calculations, transformations, or business logic that isn't available through standard tools.
1128 |
1129 | **Configuration Options**:
1130 | - `name` (string, REQUIRED): Function name that the LLM calls (must contain only letters, numbers, underscores)
1131 | - `description` (string, REQUIRED): Explains to the LLM what the tool does and when to use it
1132 | - `code` (string, REQUIRED): The actual JavaScript or Python code to execute
1133 | - `language` (string): Programming language - "javaScript" or "python" (default: "javaScript")
1134 | - `specifyInputSchema` (boolean): Whether to define input parameter schema (RECOMMENDED for validation)
1135 | - `schemaType` (string): How to define schema - "fromJson" (auto-generate from example) or "manual"
1136 | - `jsonSchemaExample` (string): Example JSON input for auto-generating schema (when schemaType="fromJson")
1137 | - `inputSchema` (string): Manual JSON schema definition (when schemaType="manual")
1138 |
1139 | **How Code Tool Works**:
1140 | The LLM calls the function by name with parameters. The code executes in a sandboxed environment and returns results to the LLM. For JavaScript, the code must return a value. For Python, use `return` statements.
1141 |
1142 | **Critical Requirements**:
1143 | 1. Function `name` must be valid identifier (letters, numbers, underscores only)
1144 | 2. `description` required to help LLM understand when to use the tool
1145 | 3. `code` must be syntactically valid and return a value
1146 | 4. Input schema HIGHLY RECOMMENDED to validate LLM-provided parameters
1147 |
1148 | **Validation Logic**:
1149 | ```typescript
1150 | function validateCodeTool(node: WorkflowNode): ValidationIssue[] {
1151 | const issues: ValidationIssue[] = [];
1152 |
1153 | // 1. Check function name (REQUIRED)
1154 | if (!node.parameters.name) {
1155 | issues.push({
1156 | severity: 'error',
1157 | message: `Code Tool "${node.name}" has no function name. Add a name property.`
1158 | });
1159 | } else if (!/^[a-zA-Z0-9_]+$/.test(node.parameters.name)) {
1160 | issues.push({
1161 | severity: 'error',
1162 | message: `Code Tool "${node.name}" function name "${node.parameters.name}" contains invalid characters. Use only letters, numbers, and underscores.`
1163 | });
1164 | } else if (/^\d/.test(node.parameters.name)) {
1165 | issues.push({
1166 | severity: 'error',
1167 | message: `Code Tool "${node.name}" function name "${node.parameters.name}" cannot start with a number.`
1168 | });
1169 | }
1170 |
1171 | // 2. Check description (REQUIRED)
1172 | if (!node.parameters.description) {
1173 | issues.push({
1174 | severity: 'error',
1175 | message: `Code Tool "${node.name}" has no description. Add one to help the LLM understand the tool's purpose.`
1176 | });
1177 | } else if (node.parameters.description.trim().length < 10) {
1178 | issues.push({
1179 | severity: 'warning',
1180 | message: `Code Tool "${node.name}" description is too short. Provide more detail about what the tool does.`
1181 | });
1182 | }
1183 |
1184 | // 3. Check code exists (REQUIRED)
1185 | if (!node.parameters.code || node.parameters.code.trim().length === 0) {
1186 | issues.push({
1187 | severity: 'error',
1188 | message: `Code Tool "${node.name}" has no code. Add the JavaScript or Python code to execute.`
1189 | });
1190 | }
1191 |
1192 | // 4. Check language validity
1193 | if (node.parameters.language && !['javaScript', 'python'].includes(node.parameters.language)) {
1194 | issues.push({
1195 | severity: 'error',
1196 | message: `Code Tool "${node.name}" has invalid language "${node.parameters.language}". Use "javaScript" or "python".`
1197 | });
1198 | }
1199 |
1200 | // 5. Recommend input schema
1201 | if (!node.parameters.specifyInputSchema) {
1202 | issues.push({
1203 | severity: 'warning',
1204 | message: `Code Tool "${node.name}" does not specify an input schema. Consider adding one to validate LLM inputs.`
1205 | });
1206 | } else {
1207 | // 6. Validate schema if specified
1208 | if (node.parameters.schemaType === 'fromJson') {
1209 | if (!node.parameters.jsonSchemaExample) {
1210 | issues.push({
1211 | severity: 'error',
1212 | message: `Code Tool "${node.name}" uses schemaType="fromJson" but has no jsonSchemaExample.`
1213 | });
1214 | } else {
1215 | try {
1216 | JSON.parse(node.parameters.jsonSchemaExample);
1217 | } catch (e) {
1218 | issues.push({
1219 | severity: 'error',
1220 | message: `Code Tool "${node.name}" has invalid JSON schema example.`
1221 | });
1222 | }
1223 | }
1224 | } else if (node.parameters.schemaType === 'manual') {
1225 | if (!node.parameters.inputSchema) {
1226 | issues.push({
1227 | severity: 'error',
1228 | message: `Code Tool "${node.name}" uses schemaType="manual" but has no inputSchema.`
1229 | });
1230 | } else {
1231 | try {
1232 | const schema = JSON.parse(node.parameters.inputSchema);
1233 | if (!schema.type) {
1234 | issues.push({
1235 | severity: 'warning',
1236 | message: `Code Tool "${node.name}" manual schema should have a 'type' field.`
1237 | });
1238 | }
1239 | if (!schema.properties && schema.type === 'object') {
1240 | issues.push({
1241 | severity: 'warning',
1242 | message: `Code Tool "${node.name}" object schema should have 'properties' field.`
1243 | });
1244 | }
1245 | } catch (e) {
1246 | issues.push({
1247 | severity: 'error',
1248 | message: `Code Tool "${node.name}" has invalid JSON schema.`
1249 | });
1250 | }
1251 | }
1252 | }
1253 | }
1254 |
1255 | // 7. Check for common code mistakes
1256 | if (node.parameters.code) {
1257 | const lang = node.parameters.language || 'javaScript';
1258 | if (lang === 'javaScript') {
1259 | // Check if code has return statement or expression
1260 | const hasReturn = /\breturn\b/.test(node.parameters.code);
1261 | const isSingleExpression = !node.parameters.code.includes(';') &&
1262 | !node.parameters.code.includes('\n');
1263 | if (!hasReturn && !isSingleExpression) {
1264 | issues.push({
1265 | severity: 'warning',
1266 | message: `Code Tool "${node.name}" JavaScript code should return a value. Add a return statement.`
1267 | });
1268 | }
1269 | }
1270 | }
1271 |
1272 | return issues;
1273 | }
1274 | ```
1275 |
1276 | **Validation Examples**:
1277 |
1278 | ✅ **Correct Example 1** - Simple calculation tool:
1279 | ```typescript
1280 | {
1281 | type: 'toolCode',
1282 | name: 'Calculate Tax',
1283 | parameters: {
1284 | name: 'calculate_tax',
1285 | description: 'Calculates sales tax for a given price and tax rate percentage',
1286 | language: 'javaScript',
1287 | code: 'return price * (taxRate / 100);',
1288 | specifyInputSchema: true,
1289 | schemaType: 'fromJson',
1290 | jsonSchemaExample: '{"price": 100, "taxRate": 8.5}'
1291 | }
1292 | }
1293 | // Valid: Has function name, description, code with return statement, and input schema
1294 | ```
1295 |
1296 | ✅ **Correct Example 2** - Python data transformation:
1297 | ```typescript
1298 | {
1299 | type: 'toolCode',
1300 | name: 'Format Date',
1301 | parameters: {
1302 | name: 'format_date',
1303 | description: 'Converts ISO date string to human-readable format',
1304 | language: 'python',
1305 | code: `from datetime import datetime
1306 | date_obj = datetime.fromisoformat(iso_date)
1307 | return date_obj.strftime('%B %d, %Y')`,
1308 | specifyInputSchema: true,
1309 | schemaType: 'manual',
1310 | inputSchema: '{"type": "object", "properties": {"iso_date": {"type": "string"}}, "required": ["iso_date"]}'
1311 | }
1312 | }
1313 | // Valid: Python code with proper return, manual schema with type and properties
1314 | ```
1315 |
1316 | ✅ **Correct Example 3** - Business logic without schema:
1317 | ```typescript
1318 | {
1319 | type: 'toolCode',
1320 | name: 'Discount Calculator',
1321 | parameters: {
1322 | name: 'apply_discount',
1323 | description: 'Applies tiered discount based on order total: 10% off over $100, 20% off over $500',
1324 | language: 'javaScript',
1325 | code: `if (total >= 500) return total * 0.8;
1326 | if (total >= 100) return total * 0.9;
1327 | return total;`
1328 | }
1329 | }
1330 | // Valid even without schema: Has name, description, and working code
1331 | // WARNING will be issued recommending schema
1332 | ```
1333 |
1334 | ❌ **Incorrect Example 1** - Invalid function name:
1335 | ```typescript
1336 | {
1337 | type: 'toolCode',
1338 | name: 'Calculate Tax',
1339 | parameters: {
1340 | name: '3rd_party_calculator', // ❌ Starts with number
1341 | description: 'Calculates sales tax',
1342 | code: 'return price * 0.085;'
1343 | }
1344 | }
1345 | // ERROR: Function name cannot start with a number
1346 | ```
1347 |
1348 | ❌ **Incorrect Example 2** - Missing required fields:
1349 | ```typescript
1350 | {
1351 | type: 'toolCode',
1352 | name: 'My Tool',
1353 | parameters: {
1354 | name: 'my_tool',
1355 | // ❌ No description
1356 | code: '' // ❌ Empty code
1357 | }
1358 | }
1359 | // ERROR: Missing description (required for LLM)
1360 | // ERROR: No code provided
1361 | ```
1362 |
1363 | ❌ **Incorrect Example 3** - Invalid schema configuration:
1364 | ```typescript
1365 | {
1366 | type: 'toolCode',
1367 | name: 'Data Processor',
1368 | parameters: {
1369 | name: 'process_data',
1370 | description: 'Processes input data',
1371 | code: 'return data.toUpperCase();',
1372 | specifyInputSchema: true,
1373 | schemaType: 'fromJson',
1374 | // ❌ No jsonSchemaExample when using fromJson
1375 | }
1376 | }
1377 | // ERROR: schemaType="fromJson" requires jsonSchemaExample
1378 | ```
1379 |
1380 | ❌ **Incorrect Example 4** - Invalid characters in name:
1381 | ```typescript
1382 | {
1383 | type: 'toolCode',
1384 | name: 'Format Name',
1385 | parameters: {
1386 | name: 'format-name-helper', // ❌ Contains hyphens
1387 | description: 'Formats user names',
1388 | code: 'return firstName + " " + lastName;'
1389 | }
1390 | }
1391 | // ERROR: Function name contains invalid characters (hyphens not allowed)
1392 | // Only letters, numbers, and underscores permitted
1393 | ```
1394 |
1395 | ### 3. Vector Store Tool (`toolVectorStore`)
1396 |
1397 | **Purpose**: Enables the AI agent to perform semantic search over a knowledge base by querying a vector store. The LLM can retrieve relevant documents or data based on natural language queries.
1398 |
1399 | **Configuration Options**:
1400 | - `name` (string, REQUIRED): Tool name that the LLM uses to invoke the search
1401 | - `description` (string, REQUIRED): Explains what knowledge base is being searched and when to use it
1402 | - `topK` (number): Number of most relevant results to return (default: 4)
1403 |
1404 | **How Vector Store Tool Works**:
1405 | The LLM calls this tool with a search query. The tool converts the query to embeddings, searches the vector store for similar embeddings, and returns the most relevant documents/chunks. This enables RAG (Retrieval Augmented Generation) patterns.
1406 |
1407 | **Critical Requirements**:
1408 | 1. MUST have `ai_vectorStore` connection to a Vector Store node (e.g., Pinecone, In-Memory Vector Store)
1409 | 2. Vector Store MUST have `ai_embedding` connection to an Embeddings node (e.g., Embeddings OpenAI)
1410 | 3. Vector Store SHOULD have `ai_document` connection to populate it with data
1411 | 4. `description` REQUIRED to help LLM understand what knowledge is searchable
1412 |
1413 | **Connection Architecture**:
1414 | ```
1415 | [Document Loader] --ai_document--> [Vector Store] <--ai_vectorStore-- [Vector Store Tool]
1416 | [Embeddings] --ai_embedding--> [Vector Store]
1417 | [Vector Store] --ai_vectorStore--> [AI Agent]
1418 | ```
1419 |
1420 | **Validation Logic**:
1421 | ```typescript
1422 | function validateVectorStoreTool(
1423 | node: WorkflowNode,
1424 | reverseConnections: Map<string, Connection[]>,
1425 | workflow: WorkflowJson
1426 | ): ValidationIssue[] {
1427 | const issues: ValidationIssue[] = [];
1428 |
1429 | // 1. Check tool name (REQUIRED)
1430 | if (!node.parameters.name) {
1431 | issues.push({
1432 | severity: 'error',
1433 | message: `Vector Store Tool "${node.name}" has no tool name. Add a name property.`
1434 | });
1435 | }
1436 |
1437 | // 2. Check description (REQUIRED)
1438 | if (!node.parameters.description) {
1439 | issues.push({
1440 | severity: 'error',
1441 | message: `Vector Store Tool "${node.name}" has no description. Add one to explain what data it searches.`
1442 | });
1443 | } else if (node.parameters.description.trim().length < 15) {
1444 | issues.push({
1445 | severity: 'warning',
1446 | message: `Vector Store Tool "${node.name}" description is too short. Explain what knowledge base is being searched.`
1447 | });
1448 | }
1449 |
1450 | // 3. Check ai_vectorStore connection (REQUIRED)
1451 | const incoming = reverseConnections.get(node.name) || [];
1452 | const vectorStoreConn = incoming.find(c => c.type === 'ai_vectorStore');
1453 |
1454 | if (!vectorStoreConn) {
1455 | issues.push({
1456 | severity: 'error',
1457 | message: `Vector Store Tool "${node.name}" requires an ai_vectorStore connection. Connect a Vector Store node (e.g., Pinecone, In-Memory Vector Store).`
1458 | });
1459 | return issues; // Can't continue without this
1460 | }
1461 |
1462 | // 4. Validate Vector Store node exists
1463 | const vectorStoreNode = workflow.nodes.find(n => n.name === vectorStoreConn.sourceName);
1464 | if (!vectorStoreNode) {
1465 | issues.push({
1466 | severity: 'error',
1467 | message: `Vector Store Tool "${node.name}" connects to non-existent node "${vectorStoreConn.sourceName}".`
1468 | });
1469 | return issues;
1470 | }
1471 |
1472 | // 5. Validate Vector Store has embedding (REQUIRED)
1473 | const vsIncoming = reverseConnections.get(vectorStoreNode.name) || [];
1474 | const embeddingConn = vsIncoming.find(c => c.type === 'ai_embedding');
1475 |
1476 | if (!embeddingConn) {
1477 | issues.push({
1478 | severity: 'error',
1479 | message: `Vector Store "${vectorStoreNode.name}" requires an ai_embedding connection. Connect an Embeddings node (e.g., Embeddings OpenAI, Embeddings Google Gemini).`
1480 | });
1481 | }
1482 |
1483 | // 6. Check for document loader (RECOMMENDED)
1484 | const documentConn = vsIncoming.find(c => c.type === 'ai_document');
1485 | if (!documentConn) {
1486 | issues.push({
1487 | severity: 'warning',
1488 | message: `Vector Store "${vectorStoreNode.name}" has no ai_document connection. Without documents, the vector store will be empty. Connect a Document Loader to populate it.`
1489 | });
1490 | }
1491 |
1492 | // 7. Validate topK parameter if specified
1493 | if (node.parameters.topK !== undefined) {
1494 | if (typeof node.parameters.topK !== 'number' || node.parameters.topK < 1) {
1495 | issues.push({
1496 | severity: 'error',
1497 | message: `Vector Store Tool "${node.name}" has invalid topK value. Must be a positive number.`
1498 | });
1499 | } else if (node.parameters.topK > 20) {
1500 | issues.push({
1501 | severity: 'warning',
1502 | message: `Vector Store Tool "${node.name}" has topK=${node.parameters.topK}. Large values may overwhelm the LLM context. Consider reducing to 10 or less.`
1503 | });
1504 | }
1505 | }
1506 |
1507 | return issues;
1508 | }
1509 | ```
1510 |
1511 | **Validation Examples**:
1512 |
1513 | ✅ **Correct Example 1** - Complete RAG setup:
1514 | ```typescript
1515 | {
1516 | type: 'toolVectorStore',
1517 | name: 'Search Knowledge Base',
1518 | parameters: {
1519 | name: 'search_docs',
1520 | description: 'Searches our product documentation and knowledge base articles to answer customer questions',
1521 | topK: 5
1522 | }
1523 | }
1524 | // Connected to:
1525 | // - In-Memory Vector Store (with ai_vectorStore connection)
1526 | // - Embeddings OpenAI (with ai_embedding connection)
1527 | // - Default Data Loader (with ai_document connection)
1528 | // Valid: Has name, description, proper connection chain
1529 | ```
1530 |
1531 | ✅ **Correct Example 2** - Pinecone integration:
1532 | ```typescript
1533 | {
1534 | type: 'toolVectorStore',
1535 | name: 'Search Customer History',
1536 | parameters: {
1537 | name: 'search_customer_data',
1538 | description: 'Searches previous customer interactions, support tickets, and feedback to provide context for current conversation',
1539 | topK: 3
1540 | }
1541 | }
1542 | // Connected to:
1543 | // - Pinecone Vector Store (with ai_vectorStore connection)
1544 | // - Embeddings Google Gemini (with ai_embedding connection)
1545 | // - CSV File Loader (with ai_document connection)
1546 | // Valid: All required connections present
1547 | ```
1548 |
1549 | ✅ **Correct Example 3** - Minimal setup:
1550 | ```typescript
1551 | {
1552 | type: 'toolVectorStore',
1553 | name: 'Search Company Policies',
1554 | parameters: {
1555 | name: 'search_policies',
1556 | description: 'Searches company policies, procedures, and guidelines to answer employee questions'
1557 | }
1558 | }
1559 | // Connected to vector store with embeddings
1560 | // Valid: Uses default topK=4, has all required components
1561 | // WARNING will be issued if no document loader connected
1562 | ```
1563 |
1564 | ❌ **Incorrect Example 1** - Missing vector store connection:
1565 | ```typescript
1566 | {
1567 | type: 'toolVectorStore',
1568 | name: 'Search Tool',
1569 | parameters: {
1570 | name: 'search',
1571 | description: 'Searches documents'
1572 | }
1573 | }
1574 | // ❌ No ai_vectorStore connection
1575 | // ERROR: Vector Store Tool requires an ai_vectorStore connection
1576 | ```
1577 |
1578 | ❌ **Incorrect Example 2** - Vector store missing embeddings:
1579 | ```typescript
1580 | {
1581 | type: 'toolVectorStore',
1582 | name: 'Search Documents',
1583 | parameters: {
1584 | name: 'search_docs',
1585 | description: 'Searches our document collection'
1586 | }
1587 | }
1588 | // Connected to: In-Memory Vector Store (no ai_embedding connection)
1589 | // ERROR: Vector Store requires an ai_embedding connection
1590 | // Without embeddings, semantic search cannot function
1591 | ```
1592 |
1593 | ❌ **Incorrect Example 3** - Missing required fields:
1594 | ```typescript
1595 | {
1596 | type: 'toolVectorStore',
1597 | name: 'Search Tool',
1598 | parameters: {
1599 | // ❌ No name property
1600 | description: 'Search' // ❌ Description too short
1601 | }
1602 | }
1603 | // ERROR: No tool name
1604 | // WARNING: Description too short (provide more detail)
1605 | ```
1606 |
1607 | ❌ **Incorrect Example 4** - Invalid topK:
1608 | ```typescript
1609 | {
1610 | type: 'toolVectorStore',
1611 | name: 'Search Everything',
1612 | parameters: {
1613 | name: 'search_all',
1614 | description: 'Searches all available documents in the knowledge base',
1615 | topK: 50 // ❌ Too many results
1616 | }
1617 | }
1618 | // WARNING: topK=50 may overwhelm LLM context
1619 | // Large result sets reduce response quality
1620 | ```
1621 |
1622 | ### 4. Workflow Tool (`toolWorkflow`)
1623 |
1624 | **Purpose**: Executes another n8n workflow as a tool, allowing complex reusable logic to be packaged as agent capabilities.
1625 |
1626 | **Configuration Options**:
1627 | - `source`: "database" (existing workflow) or "parameter" (inline workflow JSON)
1628 | - `workflowId`: ID of workflow to execute (when source="database")
1629 | - `workflowJson`: Inline workflow definition (when source="parameter")
1630 | - `description`: Tool description for LLM (REQUIRED)
1631 | - `specifyInputSchema`: Whether to define input schema (recommended)
1632 | - `workflowInputs`: Field mapping from LLM to workflow inputs
1633 |
1634 | **Critical Requirement**: Sub-workflow MUST start with "Execute Workflow Trigger" node.
1635 |
1636 | ```typescript
1637 | function validateWorkflowTool(node: WorkflowNode): ValidationIssue[] {
1638 | const issues: ValidationIssue[] = [];
1639 |
1640 | // 1. Check description (REQUIRED for LLM to understand tool)
1641 | if (!node.parameters.description) {
1642 | issues.push({
1643 | severity: 'error',
1644 | message: `Workflow Tool "${node.name}" has no description. Add a clear description to help the LLM know when to use this sub-workflow.`
1645 | });
1646 | }
1647 |
1648 | // 2. Check source parameter exists
1649 | if (!node.parameters.source) {
1650 | issues.push({
1651 | severity: 'error',
1652 | message: `Workflow Tool "${node.name}" has no source parameter. Set source to "database" or "parameter".`
1653 | });
1654 | return issues; // Can't continue without source
1655 | }
1656 |
1657 | // 3. Validate based on source type
1658 | if (node.parameters.source === 'database') {
1659 | // When using database, workflowId is required
1660 | if (!node.parameters.workflowId) {
1661 | issues.push({
1662 | severity: 'error',
1663 | message: `Workflow Tool "${node.name}" has source="database" but no workflowId specified. Select a sub-workflow to execute.`
1664 | });
1665 | }
1666 |
1667 | // Note: We can't validate if the sub-workflow exists at validation time
1668 | // because workflows are deployed independently. This should be checked at runtime.
1669 | // The sub-workflow MUST start with "Execute Workflow Trigger" node.
1670 |
1671 | } else if (node.parameters.source === 'parameter') {
1672 | // When using parameter, workflowJson is required
1673 | if (!node.parameters.workflowJson) {
1674 | issues.push({
1675 | severity: 'error',
1676 | message: `Workflow Tool "${node.name}" has source="parameter" but no workflowJson specified. Provide inline workflow definition.`
1677 | });
1678 | } else {
1679 | // Validate workflowJson is valid JSON
1680 | try {
1681 | const workflow = typeof node.parameters.workflowJson === 'string'
1682 | ? JSON.parse(node.parameters.workflowJson)
1683 | : node.parameters.workflowJson;
1684 |
1685 | // Check if workflow has nodes
1686 | if (!workflow.nodes || !Array.isArray(workflow.nodes)) {
1687 | issues.push({
1688 | severity: 'error',
1689 | message: `Workflow Tool "${node.name}" has invalid workflowJson. Missing or invalid nodes array.`
1690 | });
1691 | } else {
1692 | // Check if workflow starts with Execute Workflow Trigger
1693 | const hasTrigger = workflow.nodes.some((n: any) =>
1694 | n.type && (
1695 | n.type.includes('executeWorkflowTrigger') ||
1696 | n.type.includes('executeWorkflow')
1697 | )
1698 | );
1699 |
1700 | if (!hasTrigger) {
1701 | issues.push({
1702 | severity: 'error',
1703 | message: `Workflow Tool "${node.name}" sub-workflow does not start with "Execute Workflow Trigger". Add this trigger node to the sub-workflow.`
1704 | });
1705 | }
1706 | }
1707 | } catch (e) {
1708 | issues.push({
1709 | severity: 'error',
1710 | message: `Workflow Tool "${node.name}" has invalid workflowJson. Must be valid JSON: ${(e as Error).message}`
1711 | });
1712 | }
1713 | }
1714 | } else {
1715 | issues.push({
1716 | severity: 'error',
1717 | message: `Workflow Tool "${node.name}" has invalid source="${node.parameters.source}". Must be "database" or "parameter".`
1718 | });
1719 | }
1720 |
1721 | // 4. Recommend input schema for better LLM integration
1722 | if (!node.parameters.specifyInputSchema) {
1723 | issues.push({
1724 | severity: 'info',
1725 | message: `Workflow Tool "${node.name}" does not specify an input schema. Consider adding one to validate LLM inputs and provide better guidance.`
1726 | });
1727 | } else {
1728 | // Validate input schema if specified
1729 | if (node.parameters.schemaType === 'fromJson') {
1730 | try {
1731 | JSON.parse(node.parameters.jsonSchemaExample || '{}');
1732 | } catch (e) {
1733 | issues.push({
1734 | severity: 'error',
1735 | message: `Workflow Tool "${node.name}" has invalid JSON schema example.`
1736 | });
1737 | }
1738 | } else if (node.parameters.schemaType === 'manual') {
1739 | try {
1740 | const schema = JSON.parse(node.parameters.inputSchema || '{}');
1741 | if (!schema.type || !schema.properties) {
1742 | issues.push({
1743 | severity: 'warning',
1744 | message: `Workflow Tool "${node.name}" manual schema should have 'type' and 'properties' fields.`
1745 | });
1746 | }
1747 | } catch (e) {
1748 | issues.push({
1749 | severity: 'error',
1750 | message: `Workflow Tool "${node.name}" has invalid JSON schema.`
1751 | });
1752 | }
1753 | }
1754 | }
1755 |
1756 | // 5. Check workflowInputs configuration
1757 | if (!node.parameters.workflowInputs) {
1758 | issues.push({
1759 | severity: 'info',
1760 | message: `Workflow Tool "${node.name}" has no workflowInputs defined. Map fields to help LLM provide correct data to sub-workflow.`
1761 | });
1762 | }
1763 |
1764 | return issues;
1765 | }
1766 | ```
1767 |
1768 | **Validation Examples**:
1769 |
1770 | ✅ **CORRECT - Database Source**:
1771 | ```json
1772 | {
1773 | "type": "@n8n/n8n-nodes-langchain.toolWorkflow",
1774 | "name": "Search Knowledge Base",
1775 | "parameters": {
1776 | "description": "Searches the company knowledge base for documentation and answers",
1777 | "source": "database",
1778 | "workflowId": "abc123",
1779 | "specifyInputSchema": true,
1780 | "jsonSchemaExample": "{\"query\": \"search term\"}"
1781 | }
1782 | }
1783 | ```
1784 |
1785 | ✅ **CORRECT - Parameter Source**:
1786 | ```json
1787 | {
1788 | "type": "@n8n/n8n-nodes-langchain.toolWorkflow",
1789 | "name": "Process Order",
1790 | "parameters": {
1791 | "description": "Processes a customer order and returns confirmation",
1792 | "source": "parameter",
1793 | "workflowJson": {
1794 | "nodes": [
1795 | {
1796 | "type": "n8n-nodes-base.executeWorkflowTrigger",
1797 | "name": "Execute Workflow Trigger"
1798 | }
1799 | ]
1800 | }
1801 | }
1802 | }
1803 | ```
1804 |
1805 | ❌ **INCORRECT - Missing workflowId**:
1806 | ```json
1807 | {
1808 | "type": "@n8n/n8n-nodes-langchain.toolWorkflow",
1809 | "parameters": {
1810 | "description": "Search KB",
1811 | "source": "database"
1812 | // Missing workflowId!
1813 | }
1814 | }
1815 | ```
1816 |
1817 | ❌ **INCORRECT - Sub-workflow missing Execute Workflow Trigger**:
1818 | ```json
1819 | {
1820 | "parameters": {
1821 | "source": "parameter",
1822 | "workflowJson": {
1823 | "nodes": [
1824 | {
1825 | "type": "n8n-nodes-base.httpRequest" // Wrong! Should be executeWorkflowTrigger
1826 | }
1827 | ]
1828 | }
1829 | }
1830 | }
1831 | ```
1832 |
1833 | ### 5. Search Tools (SerpApi, Wikipedia, SearXNG, WolframAlpha)
1834 |
1835 | #### 5a. SerpApi Tool (`toolSerpApi`)
1836 |
1837 | **Purpose**: Performs Google searches via the SerpApi service, returning web search results to the AI agent. Provides access to current web information and search results.
1838 |
1839 | **Configuration Options**:
1840 | - `description` (string, OPTIONAL): Custom description for when to use Google search
1841 | - Credentials: SerpApi API key (REQUIRED)
1842 |
1843 | **How SerpApi Tool Works**:
1844 | The LLM provides a search query. The tool uses SerpApi to perform a Google search and returns relevant search results including titles, snippets, and URLs.
1845 |
1846 | **Use Cases**:
1847 | - Finding current information not in LLM training data
1848 | - Web research and fact-checking
1849 | - Finding specific websites or resources
1850 | - News and trending topics
1851 |
1852 | **Critical Requirements**:
1853 | 1. MUST have valid SerpApi credentials configured
1854 | 2. Requires active SerpApi subscription with available credits
1855 | 3. Custom description recommended to differentiate from other search tools
1856 |
1857 | **Validation Logic**:
1858 | ```typescript
1859 | function validateSerpApiTool(node: WorkflowNode): ValidationIssue[] {
1860 | const issues: ValidationIssue[] = [];
1861 |
1862 | // 1. Check credentials (REQUIRED)
1863 | if (!node.credentials || !node.credentials.serpApi) {
1864 | issues.push({
1865 | severity: 'error',
1866 | message: `SerpApi Tool "${node.name}" requires SerpApi credentials. Configure your API key.`
1867 | });
1868 | }
1869 |
1870 | // 2. Check description (RECOMMENDED)
1871 | if (!node.parameters.description) {
1872 | issues.push({
1873 | severity: 'info',
1874 | message: `SerpApi Tool "${node.name}" has no custom description. Add one to explain when to use Google search vs. other search tools.`
1875 | });
1876 | }
1877 |
1878 | return issues;
1879 | }
1880 | ```
1881 |
1882 | **Validation Examples**:
1883 |
1884 | ✅ **Correct Example**:
1885 | ```typescript
1886 | {
1887 | type: '@n8n/n8n-nodes-langchain.toolSerpApi',
1888 | name: 'Google Search',
1889 | credentials: {
1890 | serpApi: 'serpapi_credentials_id'
1891 | },
1892 | parameters: {
1893 | description: 'Search Google for current news, recent events, and general web information. Use when you need up-to-date information from the internet.'
1894 | }
1895 | }
1896 | // Valid: Has credentials and helpful description
1897 | ```
1898 |
1899 | ❌ **Incorrect Example**:
1900 | ```typescript
1901 | {
1902 | type: '@n8n/n8n-nodes-langchain.toolSerpApi',
1903 | name: 'Search'
1904 | // ❌ No credentials configured
1905 | }
1906 | // ERROR: SerpApi Tool requires credentials
1907 | ```
1908 |
1909 | #### 5b. Wikipedia Tool (`toolWikipedia`)
1910 |
1911 | **Purpose**: Searches and retrieves information from Wikipedia, providing the AI agent access to encyclopedia knowledge on a wide range of topics.
1912 |
1913 | **Configuration Options**:
1914 | - `description` (string, OPTIONAL): Custom description for when to use Wikipedia
1915 | - `language` (string): Wikipedia language code (default: "en")
1916 | - `returnType` (string): "summary" or "full" article content
1917 |
1918 | **How Wikipedia Tool Works**:
1919 | The LLM provides a topic or search query. The tool searches Wikipedia and returns article content, either as a summary or full text.
1920 |
1921 | **Use Cases**:
1922 | - General knowledge queries
1923 | - Historical information
1924 | - Biographies and notable figures
1925 | - Scientific and technical concepts
1926 | - Geographic information
1927 |
1928 | **Critical Requirements**:
1929 | 1. No credentials required (public API)
1930 | 2. Best for factual, encyclopedic information
1931 | 3. Not ideal for current events (Wikipedia has lag time)
1932 |
1933 | **Validation Logic**:
1934 | ```typescript
1935 | function validateWikipediaTool(node: WorkflowNode): ValidationIssue[] {
1936 | const issues: ValidationIssue[] = [];
1937 |
1938 | // 1. Check description (RECOMMENDED)
1939 | if (!node.parameters.description) {
1940 | issues.push({
1941 | severity: 'info',
1942 | message: `Wikipedia Tool "${node.name}" has no custom description. Add one to explain when to use Wikipedia vs. other knowledge sources.`
1943 | });
1944 | }
1945 |
1946 | // 2. Validate language if specified
1947 | if (node.parameters.language) {
1948 | const validLanguageCodes = /^[a-z]{2,3}$/; // ISO 639 codes
1949 | if (!validLanguageCodes.test(node.parameters.language)) {
1950 | issues.push({
1951 | severity: 'warning',
1952 | message: `Wikipedia Tool "${node.name}" has potentially invalid language code "${node.parameters.language}". Use ISO 639 codes (e.g., "en", "es", "fr").`
1953 | });
1954 | }
1955 | }
1956 |
1957 | return issues;
1958 | }
1959 | ```
1960 |
1961 | **Validation Examples**:
1962 |
1963 | ✅ **Correct Example 1** - Default English:
1964 | ```typescript
1965 | {
1966 | type: '@n8n/n8n-nodes-langchain.toolWikipedia',
1967 | name: 'Wikipedia',
1968 | parameters: {
1969 | description: 'Search Wikipedia for encyclopedic information on historical events, people, places, and concepts. Best for factual, well-established knowledge.'
1970 | }
1971 | }
1972 | // Valid: Simple configuration with helpful description
1973 | ```
1974 |
1975 | ✅ **Correct Example 2** - Multilingual:
1976 | ```typescript
1977 | {
1978 | type: '@n8n/n8n-nodes-langchain.toolWikipedia',
1979 | name: 'Wikipedia Spanish',
1980 | parameters: {
1981 | description: 'Search Spanish Wikipedia for information in Spanish',
1982 | language: 'es'
1983 | }
1984 | }
1985 | // Valid: Configured for Spanish Wikipedia
1986 | ```
1987 |
1988 | #### 5c. SearXNG Tool (`toolSearXng`)
1989 |
1990 | **Purpose**: Searches using a self-hosted SearXNG metasearch engine, providing privacy-focused web search aggregated from multiple search engines.
1991 |
1992 | **Configuration Options**:
1993 | - `description` (string, OPTIONAL): Custom description for when to use SearXNG
1994 | - Credentials: SearXNG instance URL and optional API key (REQUIRED)
1995 | - `categories` (array): Search categories (general, images, news, etc.)
1996 |
1997 | **How SearXNG Tool Works**:
1998 | The LLM provides a search query. The tool queries your SearXNG instance which aggregates results from multiple search engines (Google, Bing, DuckDuckGo, etc.) and returns combined results.
1999 |
2000 | **Use Cases**:
2001 | - Privacy-focused web search
2002 | - Aggregated results from multiple sources
2003 | - Self-hosted search infrastructure
2004 | - Custom search engine configuration
2005 |
2006 | **Critical Requirements**:
2007 | 1. MUST have SearXNG instance URL configured
2008 | 2. Instance must be accessible from n8n
2009 | 3. Optional API key if instance requires authentication
2010 | 4. Requires self-hosted or third-party SearXNG instance
2011 |
2012 | **Validation Logic**:
2013 | ```typescript
2014 | function validateSearXngTool(node: WorkflowNode): ValidationIssue[] {
2015 | const issues: ValidationIssue[] = [];
2016 |
2017 | // 1. Check credentials (REQUIRED)
2018 | if (!node.credentials || !node.credentials.searXng) {
2019 | issues.push({
2020 | severity: 'error',
2021 | message: `SearXNG Tool "${node.name}" requires SearXNG instance credentials. Configure your instance URL.`
2022 | });
2023 | }
2024 |
2025 | // 2. Check description (RECOMMENDED)
2026 | if (!node.parameters.description) {
2027 | issues.push({
2028 | severity: 'info',
2029 | message: `SearXNG Tool "${node.name}" has no custom description. Add one to explain when to use SearXNG vs. other search tools.`
2030 | });
2031 | }
2032 |
2033 | return issues;
2034 | }
2035 | ```
2036 |
2037 | **Validation Examples**:
2038 |
2039 | ✅ **Correct Example**:
2040 | ```typescript
2041 | {
2042 | type: '@n8n/n8n-nodes-langchain.toolSearXng',
2043 | name: 'Privacy Search',
2044 | credentials: {
2045 | searXng: 'searxng_credentials_id' // Contains instance URL
2046 | },
2047 | parameters: {
2048 | description: 'Privacy-focused metasearch aggregating results from multiple search engines. Use for general web searches.',
2049 | categories: ['general', 'news']
2050 | }
2051 | }
2052 | // Valid: Has credentials and configuration
2053 | ```
2054 |
2055 | ❌ **Incorrect Example**:
2056 | ```typescript
2057 | {
2058 | type: '@n8n/n8n-nodes-langchain.toolSearXng',
2059 | name: 'Search'
2060 | // ❌ No credentials configured
2061 | }
2062 | // ERROR: SearXNG Tool requires instance credentials
2063 | ```
2064 |
2065 | #### 5d. WolframAlpha Tool (`toolWolframAlpha`)
2066 |
2067 | **Purpose**: Queries Wolfram|Alpha computational knowledge engine for mathematical computations, scientific data, statistics, and factual queries.
2068 |
2069 | **Configuration Options**:
2070 | - `description` (string, OPTIONAL): Custom description for when to use Wolfram|Alpha
2071 | - Credentials: Wolfram|Alpha API key (REQUIRED)
2072 |
2073 | **How WolframAlpha Tool Works**:
2074 | The LLM provides a computational or factual query. The tool sends it to Wolfram|Alpha's API and returns computed results, data, or answers.
2075 |
2076 | **Use Cases**:
2077 | - Complex mathematical computations
2078 | - Scientific calculations and conversions
2079 | - Statistical data queries
2080 | - Physics, chemistry, astronomy calculations
2081 | - Unit conversions
2082 | - Factual data (population, dates, distances, etc.)
2083 |
2084 | **Critical Requirements**:
2085 | 1. MUST have valid Wolfram|Alpha App ID (API key)
2086 | 2. Best for computational and scientific queries
2087 | 3. Not ideal for general web search or current news
2088 |
2089 | **Validation Logic**:
2090 | ```typescript
2091 | function validateWolframAlphaTool(node: WorkflowNode): ValidationIssue[] {
2092 | const issues: ValidationIssue[] = [];
2093 |
2094 | // 1. Check credentials (REQUIRED)
2095 | if (!node.credentials || !node.credentials.wolframAlpha) {
2096 | issues.push({
2097 | severity: 'error',
2098 | message: `WolframAlpha Tool "${node.name}" requires Wolfram|Alpha API credentials. Configure your App ID.`
2099 | });
2100 | }
2101 |
2102 | // 2. Check description (RECOMMENDED)
2103 | if (!node.parameters.description) {
2104 | issues.push({
2105 | severity: 'info',
2106 | message: `WolframAlpha Tool "${node.name}" has no custom description. Add one to explain when to use Wolfram|Alpha for computational queries.`
2107 | });
2108 | }
2109 |
2110 | return issues;
2111 | }
2112 | ```
2113 |
2114 | **Validation Examples**:
2115 |
2116 | ✅ **Correct Example**:
2117 | ```typescript
2118 | {
2119 | type: '@n8n/n8n-nodes-langchain.toolWolframAlpha',
2120 | name: 'Wolfram Computation',
2121 | credentials: {
2122 | wolframAlpha: 'wolfram_credentials_id'
2123 | },
2124 | parameters: {
2125 | description: 'Use for complex mathematical calculations, scientific computations, unit conversions, and factual data queries (population, distances, dates). NOT for general web search.'
2126 | }
2127 | }
2128 | // Valid: Has credentials and clear usage guidance
2129 | ```
2130 |
2131 | ❌ **Incorrect Example**:
2132 | ```typescript
2133 | {
2134 | type: '@n8n/n8n-nodes-langchain.toolWolframAlpha',
2135 | name: 'Calculator'
2136 | // ❌ No credentials configured
2137 | }
2138 | // ERROR: WolframAlpha Tool requires API credentials
2139 | ```
2140 |
2141 | ### 6. Simple Tools (Calculator, Think)
2142 |
2143 | #### 6a. Calculator Tool (`toolCalculator`)
2144 |
2145 | **Purpose**: Performs mathematical calculations and arithmetic operations. The LLM can use this tool when it needs to compute exact numerical results.
2146 |
2147 | **Configuration Options**:
2148 | - `description` (string, OPTIONAL): Custom description for when the LLM should use this calculator
2149 |
2150 | **How Calculator Tool Works**:
2151 | The LLM calls this tool with mathematical expressions as strings. The tool evaluates the expression and returns the numerical result. Handles basic arithmetic, exponents, and mathematical functions.
2152 |
2153 | **Use Cases**:
2154 | - Precise arithmetic calculations
2155 | - Financial computations
2156 | - Unit conversions requiring math
2157 | - Any task requiring exact numerical results
2158 |
2159 | **Critical Requirements**:
2160 | 1. No special configuration required - works out of the box
2161 | 2. No AI connections needed (self-contained)
2162 | 3. Custom description optional but can help guide LLM usage
2163 |
2164 | **Validation Logic**:
2165 | ```typescript
2166 | function validateCalculatorTool(node: WorkflowNode): ValidationIssue[] {
2167 | const issues: ValidationIssue[] = [];
2168 |
2169 | // Calculator is self-contained and requires no configuration
2170 | // Optional: Check for custom description
2171 | if (node.parameters.description) {
2172 | if (node.parameters.description.trim().length < 10) {
2173 | issues.push({
2174 | severity: 'info',
2175 | message: `Calculator Tool "${node.name}" has a very short description. Consider being more specific about when to use it.`
2176 | });
2177 | }
2178 | }
2179 |
2180 | return issues;
2181 | }
2182 | ```
2183 |
2184 | **Validation Examples**:
2185 |
2186 | ✅ **Correct Example 1** - Default calculator:
2187 | ```typescript
2188 | {
2189 | type: '@n8n/n8n-nodes-langchain.toolCalculator',
2190 | name: 'Calculator'
2191 | }
2192 | // Valid: No configuration needed, works with defaults
2193 | ```
2194 |
2195 | ✅ **Correct Example 2** - Custom description:
2196 | ```typescript
2197 | {
2198 | type: '@n8n/n8n-nodes-langchain.toolCalculator',
2199 | name: 'Financial Calculator',
2200 | parameters: {
2201 | description: 'Use for precise financial calculations, tax computations, and percentage calculations. Always use this instead of estimating numbers.'
2202 | }
2203 | }
2204 | // Valid: Custom description guides LLM on specific use case
2205 | ```
2206 |
2207 | #### 6b. Think Tool (`toolThink`)
2208 |
2209 | **Purpose**: Gives the AI agent time to think, reason, and plan before taking action. The agent can "think out loud" to work through complex problems step by step.
2210 |
2211 | **Configuration Options**:
2212 | - `description` (string, OPTIONAL): Custom description for when the LLM should pause to think
2213 |
2214 | **How Think Tool Works**:
2215 | When the LLM calls this tool, it returns the thinking content back to the agent. This creates a feedback loop where the agent can reason through problems, consider alternatives, and plan multi-step approaches before executing actions.
2216 |
2217 | **Use Cases**:
2218 | - Complex problem-solving requiring multi-step reasoning
2219 | - Planning sequences of actions
2220 | - Considering trade-offs and alternatives
2221 | - Breaking down complex tasks
2222 | - Self-correction and validation
2223 |
2224 | **Critical Requirements**:
2225 | 1. No special configuration required
2226 | 2. No AI connections needed (self-contained)
2227 | 3. Most useful when agent faces complex, multi-step problems
2228 |
2229 | **Validation Logic**:
2230 | ```typescript
2231 | function validateThinkTool(node: WorkflowNode): ValidationIssue[] {
2232 | const issues: ValidationIssue[] = [];
2233 |
2234 | // Think tool is self-contained and requires no configuration
2235 | // Optional: Check for custom description
2236 | if (node.parameters.description) {
2237 | if (node.parameters.description.trim().length < 15) {
2238 | issues.push({
2239 | severity: 'info',
2240 | message: `Think Tool "${node.name}" has a very short description. Explain when the agent should use thinking vs. action.`
2241 | });
2242 | }
2243 | }
2244 |
2245 | return issues;
2246 | }
2247 | ```
2248 |
2249 | **Validation Examples**:
2250 |
2251 | ✅ **Correct Example 1** - Default think tool:
2252 | ```typescript
2253 | {
2254 | type: '@n8n/n8n-nodes-langchain.toolThink',
2255 | name: 'Think'
2256 | }
2257 | // Valid: No configuration needed, works with defaults
2258 | ```
2259 |
2260 | ✅ **Correct Example 2** - Custom description for complex reasoning:
2261 | ```typescript
2262 | {
2263 | type: '@n8n/n8n-nodes-langchain.toolThink',
2264 | name: 'Strategic Planner',
2265 | parameters: {
2266 | description: 'Use this tool when you need to plan a complex multi-step approach, consider trade-offs between options, or validate your reasoning before taking action. Think through edge cases and potential failures.'
2267 | }
2268 | }
2269 | // Valid: Detailed description guides agent on when to think vs. act
2270 | ```
2271 |
2272 | ✅ **Correct Example 3** - Problem-solving focus:
2273 | ```typescript
2274 | {
2275 | type: '@n8n/n8n-nodes-langchain.toolThink',
2276 | name: 'Reasoning Tool',
2277 | parameters: {
2278 | description: 'Break down complex problems into steps, identify what information is missing, and plan your approach before using other tools'
2279 | }
2280 | }
2281 | // Valid: Focuses agent on structured problem-solving
2282 | ```
2283 |
2284 | ### 7. AI Agent Tool (`agentTool`)
2285 |
2286 | **Purpose**: Creates a nested AI agent that functions as a tool for a parent AI agent. Enables complex agent hierarchies where specialized sub-agents handle specific tasks, each with their own model, tools, and capabilities.
2287 |
2288 | **Configuration Options**:
2289 | - `name` (string, REQUIRED): Tool name that the parent agent uses to invoke this sub-agent
2290 | - `description` (string, REQUIRED): Explains the sub-agent's capabilities and when the parent should use it
2291 | - `promptType` (string): "auto" or "define" - how to construct prompts for this sub-agent
2292 | - `text` (string): Custom system prompt (when promptType="define")
2293 | - `systemMessage` (string): System message defining sub-agent's role
2294 | - `maxIterations` (number): Maximum tool-calling iterations (default: 10)
2295 | - `returnIntermediateSteps` (boolean): Return sub-agent's reasoning steps to parent
2296 |
2297 | **How AI Agent Tool Works**:
2298 | The parent AI agent can invoke this sub-agent as a tool. The sub-agent has its own language model, tools, and configuration. It processes the request independently and returns results to the parent. This creates hierarchical agent architectures.
2299 |
2300 | **Use Cases**:
2301 | - Specialized experts (e.g., "SQL Query Expert" sub-agent with database tools)
2302 | - Complex multi-step workflows (e.g., "Research Assistant" that uses search + summarization)
2303 | - Domain-specific processing (e.g., "Financial Analysis Agent" with calculation tools)
2304 |
2305 | **Critical Requirements**:
2306 | 1. MUST have exactly 1 `ai_languageModel` connection (the sub-agent's model)
2307 | 2. `name` and `description` REQUIRED for parent agent to invoke properly
2308 | 3. Can have its own `ai_tool` connections (sub-agent's toolset)
2309 | 4. Can have `ai_memory` connection (sub-agent's memory)
2310 | 5. Should have clear systemMessage defining sub-agent's specialized role
2311 |
2312 | **Connection Architecture**:
2313 | ```
2314 | [Language Model] --ai_languageModel--> [AI Agent Tool] --ai_tool--> [Parent AI Agent]
2315 | [Tool 1] --ai_tool-----------> [AI Agent Tool]
2316 | [Tool 2] --ai_tool-----------> [AI Agent Tool]
2317 | ```
2318 |
2319 | **Validation Logic**:
2320 | ```typescript
2321 | function validateAIAgentTool(
2322 | node: WorkflowNode,
2323 | reverseConnections: Map<string, Connection[]>
2324 | ): ValidationIssue[] {
2325 | const issues: ValidationIssue[] = [];
2326 |
2327 | // This is an AI Agent packaged as a tool
2328 | // It has the same requirements as a regular AI Agent
2329 |
2330 | // 1. Check ai_languageModel connection (REQUIRED, exactly 1)
2331 | const incoming = reverseConnections.get(node.name) || [];
2332 | const languageModelConn = incoming.filter(c => c.type === 'ai_languageModel');
2333 |
2334 | if (languageModelConn.length === 0) {
2335 | issues.push({
2336 | severity: 'error',
2337 | message: `AI Agent Tool "${node.name}" requires an ai_languageModel connection. Connect a language model node.`
2338 | });
2339 | } else if (languageModelConn.length > 1) {
2340 | issues.push({
2341 | severity: 'error',
2342 | message: `AI Agent Tool "${node.name}" has ${languageModelConn.length} ai_languageModel connections. AI Agent Tool only supports 1 language model (no fallback).`
2343 | });
2344 | }
2345 |
2346 | // 2. Check tool name (REQUIRED)
2347 | if (!node.parameters.name) {
2348 | issues.push({
2349 | severity: 'error',
2350 | message: `AI Agent Tool "${node.name}" has no tool name. Add a name so the parent agent can invoke this sub-agent.`
2351 | });
2352 | }
2353 |
2354 | // 3. Check description (REQUIRED)
2355 | if (!node.parameters.description) {
2356 | issues.push({
2357 | severity: 'error',
2358 | message: `AI Agent Tool "${node.name}" has no description. Add one to help the parent agent know when to use this sub-agent.`
2359 | });
2360 | } else if (node.parameters.description.trim().length < 20) {
2361 | issues.push({
2362 | severity: 'warning',
2363 | message: `AI Agent Tool "${node.name}" description is too short. Explain the sub-agent's specific expertise and capabilities.`
2364 | });
2365 | }
2366 |
2367 | // 4. Check system message (RECOMMENDED)
2368 | if (!node.parameters.systemMessage && node.parameters.promptType !== 'define') {
2369 | issues.push({
2370 | severity: 'warning',
2371 | message: `AI Agent Tool "${node.name}" has no systemMessage. Add one to define the sub-agent's specialized role and constraints.`
2372 | });
2373 | }
2374 |
2375 | // 5. Validate promptType configuration
2376 | if (node.parameters.promptType === 'define') {
2377 | if (!node.parameters.text || node.parameters.text.trim() === '') {
2378 | issues.push({
2379 | severity: 'error',
2380 | message: `AI Agent Tool "${node.name}" has promptType="define" but no text field. Provide the custom prompt.`
2381 | });
2382 | }
2383 | }
2384 |
2385 | // 6. Check if sub-agent has its own tools
2386 | const toolConnections = incoming.filter(c => c.type === 'ai_tool');
2387 | if (toolConnections.length === 0) {
2388 | issues.push({
2389 | severity: 'info',
2390 | message: `AI Agent Tool "${node.name}" has no ai_tool connections. Consider giving the sub-agent tools to enhance its capabilities.`
2391 | });
2392 | }
2393 |
2394 | // 7. Validate maxIterations if specified
2395 | if (node.parameters.maxIterations !== undefined) {
2396 | if (typeof node.parameters.maxIterations !== 'number' || node.parameters.maxIterations < 1) {
2397 | issues.push({
2398 | severity: 'error',
2399 | message: `AI Agent Tool "${node.name}" has invalid maxIterations. Must be a positive number.`
2400 | });
2401 | }
2402 | }
2403 |
2404 | return issues;
2405 | }
2406 | ```
2407 |
2408 | **Validation Examples**:
2409 |
2410 | ✅ **Correct Example 1** - Specialized SQL expert sub-agent:
2411 | ```typescript
2412 | {
2413 | type: '@n8n/n8n-nodes-langchain.agentTool',
2414 | name: 'SQL Expert',
2415 | parameters: {
2416 | name: 'sql_expert',
2417 | description: 'Expert SQL analyst that can query databases, analyze data patterns, and generate complex queries. Use when you need database insights or data analysis.',
2418 | systemMessage: 'You are a SQL expert. Generate optimized SQL queries and explain query plans. Always validate input before querying.',
2419 | maxIterations: 5
2420 | }
2421 | }
2422 | // Connected to:
2423 | // - OpenAI Chat Model (with ai_languageModel connection)
2424 | // - Postgres Tool (with ai_tool connection)
2425 | // - Code Tool for data analysis (with ai_tool connection)
2426 | // Valid: Has model, name, description, tools, specialized system message
2427 | ```
2428 |
2429 | ✅ **Correct Example 2** - Research assistant sub-agent:
2430 | ```typescript
2431 | {
2432 | type: '@n8n/n8n-nodes-langchain.agentTool',
2433 | name: 'Research Assistant',
2434 | parameters: {
2435 | name: 'research_assistant',
2436 | description: 'Specialized research agent that searches the web, analyzes sources, and synthesizes information. Use for fact-finding and research tasks.',
2437 | systemMessage: 'You are a research assistant. Search multiple sources, verify information, cite sources, and provide comprehensive summaries.',
2438 | returnIntermediateSteps: true
2439 | }
2440 | }
2441 | // Connected to:
2442 | // - Anthropic Chat Model (with ai_languageModel connection)
2443 | // - SerpApi Tool (with ai_tool connection)
2444 | // - Wikipedia Tool (with ai_tool connection)
2445 | // - Vector Store Tool (with ai_tool connection)
2446 | // Valid: Multi-tool sub-agent with clear specialization
2447 | ```
2448 |
2449 | ✅ **Correct Example 3** - Minimal sub-agent:
2450 | ```typescript
2451 | {
2452 | type: '@n8n/n8n-nodes-langchain.agentTool',
2453 | name: 'Calculator Agent',
2454 | parameters: {
2455 | name: 'calculator',
2456 | description: 'Simple calculator agent for basic arithmetic operations',
2457 | systemMessage: 'You are a calculator. Perform accurate arithmetic calculations.'
2458 | }
2459 | }
2460 | // Connected to:
2461 | // - OpenAI Chat Model (with ai_languageModel connection)
2462 | // - Calculator Tool (with ai_tool connection)
2463 | // Valid: Simple but complete configuration
2464 | // INFO will suggest adding more tools
2465 | ```
2466 |
2467 | ❌ **Incorrect Example 1** - Missing language model:
2468 | ```typescript
2469 | {
2470 | type: '@n8n/n8n-nodes-langchain.agentTool',
2471 | name: 'Helper Agent',
2472 | parameters: {
2473 | name: 'helper',
2474 | description: 'Helps with tasks'
2475 | }
2476 | }
2477 | // ❌ No ai_languageModel connection
2478 | // ERROR: AI Agent Tool requires an ai_languageModel connection
2479 | ```
2480 |
2481 | ❌ **Incorrect Example 2** - Missing required fields:
2482 | ```typescript
2483 | {
2484 | type: '@n8n/n8n-nodes-langchain.agentTool',
2485 | name: 'Agent Tool',
2486 | parameters: {
2487 | // ❌ No name property
2488 | description: 'Agent' // ❌ Description too short
2489 | }
2490 | }
2491 | // ERROR: No tool name
2492 | // WARNING: Description too short (explain sub-agent's expertise)
2493 | ```
2494 |
2495 | ❌ **Incorrect Example 3** - Multiple language models:
2496 | ```typescript
2497 | {
2498 | type: '@n8n/n8n-nodes-langchain.agentTool',
2499 | name: 'Dual Model Agent',
2500 | parameters: {
2501 | name: 'dual_agent',
2502 | description: 'Agent with fallback model support'
2503 | }
2504 | }
2505 | // Connected to:
2506 | // - OpenAI Chat Model (with ai_languageModel connection)
2507 | // - Anthropic Chat Model (with ai_languageModel connection) // ❌ Second model
2508 | // ERROR: AI Agent Tool has 2 ai_languageModel connections. Only 1 allowed (no fallback support)
2509 | ```
2510 |
2511 | ❌ **Incorrect Example 4** - Invalid promptType configuration:
2512 | ```typescript
2513 | {
2514 | type: '@n8n/n8n-nodes-langchain.agentTool',
2515 | name: 'Custom Agent',
2516 | parameters: {
2517 | name: 'custom',
2518 | description: 'Custom agent with specific prompt',
2519 | promptType: 'define',
2520 | // ❌ No text field when using define mode
2521 | }
2522 | }
2523 | // ERROR: promptType="define" requires text field with custom prompt
2524 | ```
2525 |
2526 | ### 8. MCP Client Tool (`mcpClientTool`)
2527 |
2528 | **Purpose**: Connects to Model Context Protocol (MCP) servers to access external tools and resources, allowing AI agents to use MCP-compliant tools.
2529 |
2530 | **Configuration Options**:
2531 | - `mcpServer`: MCP server connection configuration (REQUIRED)
2532 | - Can reference existing server or define new one
2533 | - `tool`: Specific MCP tool to use from the server (REQUIRED)
2534 | - `description`: Tool description for LLM (REQUIRED)
2535 | - `toolParameters`: Tool-specific parameters
2536 | - `useCustomInputSchema`: Whether to override tool's input schema
2537 |
2538 | **MCP Server Configuration**:
2539 | - `transport`: "stdio" or "sse" (Server-Sent Events)
2540 | - `command`: Executable command (for stdio)
2541 | - `args`: Command arguments (for stdio)
2542 | - `url`: Server URL (for SSE)
2543 | - `env`: Environment variables
2544 |
2545 | **Critical Requirements**:
2546 | 1. MCP server must be properly configured and accessible
2547 | 2. Selected tool must exist on the MCP server
2548 | 3. Tool parameters must match the tool's input schema
2549 |
2550 | ```typescript
2551 | function validateMCPClientTool(node: WorkflowNode): ValidationIssue[] {
2552 | const issues: ValidationIssue[] = [];
2553 |
2554 | // 1. Check description (REQUIRED for LLM to understand tool)
2555 | if (!node.parameters.description) {
2556 | issues.push({
2557 | severity: 'error',
2558 | message: `MCP Client Tool "${node.name}" has no description. Add a clear description to help the LLM know when to use this MCP tool.`
2559 | });
2560 | }
2561 |
2562 | // 2. Check MCP server is configured (REQUIRED)
2563 | if (!node.parameters.mcpServer) {
2564 | issues.push({
2565 | severity: 'error',
2566 | message: `MCP Client Tool "${node.name}" has no MCP server configured. Select or configure an MCP server connection.`
2567 | });
2568 | return issues; // Can't continue without server
2569 | }
2570 |
2571 | // 3. Validate MCP server configuration
2572 | const mcpServer = node.parameters.mcpServer;
2573 |
2574 | if (typeof mcpServer === 'object') {
2575 | // Inline server configuration
2576 | if (!mcpServer.transport) {
2577 | issues.push({
2578 | severity: 'error',
2579 | message: `MCP Client Tool "${node.name}" has MCP server with no transport specified. Set transport to "stdio" or "sse".`
2580 | });
2581 | } else if (mcpServer.transport === 'stdio') {
2582 | // Stdio transport requires command
2583 | if (!mcpServer.command) {
2584 | issues.push({
2585 | severity: 'error',
2586 | message: `MCP Client Tool "${node.name}" uses stdio transport but has no command specified. Provide the executable command.`
2587 | });
2588 | }
2589 | } else if (mcpServer.transport === 'sse') {
2590 | // SSE transport requires URL
2591 | if (!mcpServer.url) {
2592 | issues.push({
2593 | severity: 'error',
2594 | message: `MCP Client Tool "${node.name}" uses SSE transport but has no URL specified. Provide the server URL.`
2595 | });
2596 | } else {
2597 | // Validate URL format
2598 | try {
2599 | new URL(mcpServer.url);
2600 | } catch (e) {
2601 | issues.push({
2602 | severity: 'error',
2603 | message: `MCP Client Tool "${node.name}" has invalid server URL: ${mcpServer.url}`
2604 | });
2605 | }
2606 | }
2607 | } else {
2608 | issues.push({
2609 | severity: 'error',
2610 | message: `MCP Client Tool "${node.name}" has invalid transport "${mcpServer.transport}". Must be "stdio" or "sse".`
2611 | });
2612 | }
2613 | }
2614 |
2615 | // 4. Check tool is selected (REQUIRED)
2616 | if (!node.parameters.tool) {
2617 | issues.push({
2618 | severity: 'error',
2619 | message: `MCP Client Tool "${node.name}" has no tool selected. Select which MCP tool to use from the server.`
2620 | });
2621 | }
2622 |
2623 | // 5. Validate tool parameters if specified
2624 | if (node.parameters.toolParameters) {
2625 | try {
2626 | // Check if toolParameters is valid JSON
2627 | if (typeof node.parameters.toolParameters === 'string') {
2628 | JSON.parse(node.parameters.toolParameters);
2629 | }
2630 | } catch (e) {
2631 | issues.push({
2632 | severity: 'error',
2633 | message: `MCP Client Tool "${node.name}" has invalid toolParameters. Must be valid JSON.`
2634 | });
2635 | }
2636 | }
2637 |
2638 | // 6. Validate custom input schema if specified
2639 | if (node.parameters.useCustomInputSchema) {
2640 | if (!node.parameters.inputSchema) {
2641 | issues.push({
2642 | severity: 'error',
2643 | message: `MCP Client Tool "${node.name}" has useCustomInputSchema=true but no inputSchema provided.`
2644 | });
2645 | } else {
2646 | try {
2647 | const schema = typeof node.parameters.inputSchema === 'string'
2648 | ? JSON.parse(node.parameters.inputSchema)
2649 | : node.parameters.inputSchema;
2650 |
2651 | if (!schema.type || !schema.properties) {
2652 | issues.push({
2653 | severity: 'warning',
2654 | message: `MCP Client Tool "${node.name}" input schema should have 'type' and 'properties' fields for proper validation.`
2655 | });
2656 | }
2657 | } catch (e) {
2658 | issues.push({
2659 | severity: 'error',
2660 | message: `MCP Client Tool "${node.name}" has invalid inputSchema. Must be valid JSON Schema.`
2661 | });
2662 | }
2663 | }
2664 | }
2665 |
2666 | // 7. Recommend server name for better management
2667 | if (typeof mcpServer === 'object' && !mcpServer.name) {
2668 | issues.push({
2669 | severity: 'info',
2670 | message: `MCP Client Tool "${node.name}" MCP server has no name. Add a name for better server management and debugging.`
2671 | });
2672 | }
2673 |
2674 | return issues;
2675 | }
2676 | ```
2677 |
2678 | **Validation Examples**:
2679 |
2680 | ✅ **CORRECT - Stdio Transport**:
2681 | ```json
2682 | {
2683 | "type": "@n8n/n8n-nodes-langchain.mcpClientTool",
2684 | "name": "Filesystem Access",
2685 | "parameters": {
2686 | "description": "Access filesystem to read and write files",
2687 | "mcpServer": {
2688 | "name": "filesystem-server",
2689 | "transport": "stdio",
2690 | "command": "npx",
2691 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
2692 | "env": {}
2693 | },
2694 | "tool": "read_file"
2695 | }
2696 | }
2697 | ```
2698 |
2699 | ✅ **CORRECT - SSE Transport**:
2700 | ```json
2701 | {
2702 | "type": "@n8n/n8n-nodes-langchain.mcpClientTool",
2703 | "name": "Remote API Access",
2704 | "parameters": {
2705 | "description": "Access remote API through MCP server",
2706 | "mcpServer": {
2707 | "name": "api-server",
2708 | "transport": "sse",
2709 | "url": "https://mcp.example.com/api"
2710 | },
2711 | "tool": "fetch_data",
2712 | "toolParameters": "{\"endpoint\": \"/users\"}"
2713 | }
2714 | }
2715 | ```
2716 |
2717 | ✅ **CORRECT - With Custom Input Schema**:
2718 | ```json
2719 | {
2720 | "type": "@n8n/n8n-nodes-langchain.mcpClientTool",
2721 | "parameters": {
2722 | "description": "Search database with custom validation",
2723 | "mcpServer": "server-ref-123",
2724 | "tool": "search",
2725 | "useCustomInputSchema": true,
2726 | "inputSchema": {
2727 | "type": "object",
2728 | "properties": {
2729 | "query": {"type": "string"},
2730 | "limit": {"type": "number", "maximum": 100}
2731 | },
2732 | "required": ["query"]
2733 | }
2734 | }
2735 | }
2736 | ```
2737 |
2738 | ❌ **INCORRECT - Missing MCP Server**:
2739 | ```json
2740 | {
2741 | "type": "@n8n/n8n-nodes-langchain.mcpClientTool",
2742 | "parameters": {
2743 | "description": "Access files",
2744 | "tool": "read_file"
2745 | // Missing mcpServer!
2746 | }
2747 | }
2748 | ```
2749 |
2750 | ❌ **INCORRECT - Stdio Without Command**:
2751 | ```json
2752 | {
2753 | "parameters": {
2754 | "mcpServer": {
2755 | "transport": "stdio"
2756 | // Missing command!
2757 | },
2758 | "tool": "read_file"
2759 | }
2760 | }
2761 | ```
2762 |
2763 | ❌ **INCORRECT - SSE Without URL**:
2764 | ```json
2765 | {
2766 | "parameters": {
2767 | "mcpServer": {
2768 | "transport": "sse"
2769 | // Missing url!
2770 | },
2771 | "tool": "fetch_data"
2772 | }
2773 | }
2774 | ```
2775 |
2776 | ❌ **INCORRECT - Missing Tool Selection**:
2777 | ```json
2778 | {
2779 | "parameters": {
2780 | "description": "Access MCP server",
2781 | "mcpServer": {
2782 | "transport": "stdio",
2783 | "command": "mcp-server"
2784 | }
2785 | // Missing tool selection!
2786 | }
2787 | }
2788 | ```
2789 |
2790 | **Common MCP Server Configurations**:
2791 |
2792 | **Filesystem Server**:
2793 | ```json
2794 | {
2795 | "transport": "stdio",
2796 | "command": "npx",
2797 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
2798 | }
2799 | ```
2800 |
2801 | **GitHub Server**:
2802 | ```json
2803 | {
2804 | "transport": "stdio",
2805 | "command": "npx",
2806 | "args": ["-y", "@modelcontextprotocol/server-github"],
2807 | "env": {
2808 | "GITHUB_PERSONAL_ACCESS_TOKEN": "{{ $credentials.githubToken }}"
2809 | }
2810 | }
2811 | ```
2812 |
2813 | **PostgreSQL Server**:
2814 | ```json
2815 | {
2816 | "transport": "stdio",
2817 | "command": "npx",
2818 | "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."]
2819 | }
2820 | ```
2821 |
2822 | **Puppeteer Server**:
2823 | ```json
2824 | {
2825 | "transport": "stdio",
2826 | "command": "npx",
2827 | "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
2828 | }
2829 | ```
2830 |
2831 | **Remote SSE Server**:
2832 | ```json
2833 | {
2834 | "transport": "sse",
2835 | "url": "https://your-mcp-server.com/sse"
2836 | }
2837 | ```
2838 |
2839 | ## Complete Tool Validation Function
2840 |
2841 | ```typescript
2842 | function validateAllToolNodes(
2843 | workflow: WorkflowJson,
2844 | reverseConnections: Map<string, Connection[]>,
2845 | result: WorkflowValidationResult
2846 | ): void {
2847 | for (const node of workflow.nodes) {
2848 | const normalizedType = NodeTypeNormalizer.normalizeToFullForm(node.type);
2849 |
2850 | let issues: ValidationIssue[] = [];
2851 |
2852 | switch (normalizedType) {
2853 | case '@n8n/n8n-nodes-langchain.toolHttpRequest':
2854 | issues = validateHTTPRequestTool(node);
2855 | break;
2856 |
2857 | case '@n8n/n8n-nodes-langchain.toolCode':
2858 | issues = validateCodeTool(node);
2859 | break;
2860 |
2861 | case '@n8n/n8n-nodes-langchain.toolVectorStore':
2862 | issues = validateVectorStoreTool(node, reverseConnections, workflow);
2863 | break;
2864 |
2865 | case '@n8n/n8n-nodes-langchain.toolWorkflow':
2866 | issues = validateWorkflowTool(node);
2867 | break;
2868 |
2869 | case '@n8n/n8n-nodes-langchain.toolSerpApi':
2870 | case '@n8n/n8n-nodes-langchain.toolWikipedia':
2871 | case '@n8n/n8n-nodes-langchain.toolSearXng':
2872 | case '@n8n/n8n-nodes-langchain.toolWolframAlpha':
2873 | issues = validateSearchTool(node);
2874 | break;
2875 |
2876 | case '@n8n/n8n-nodes-langchain.agentTool':
2877 | issues = validateAIAgentTool(node, reverseConnections);
2878 | break;
2879 |
2880 | case '@n8n/n8n-nodes-langchain.mcpClientTool':
2881 | issues = validateMCPClientTool(node);
2882 | break;
2883 |
2884 | case '@n8n/n8n-nodes-langchain.toolCalculator':
2885 | case '@n8n/n8n-nodes-langchain.toolThink':
2886 | issues = validateSimpleTool(node);
2887 | break;
2888 | }
2889 |
2890 | // Add issues to result
2891 | for (const issue of issues) {
2892 | if (issue.severity === 'error') {
2893 | result.errors.push({
2894 | type: 'error',
2895 | nodeId: node.id,
2896 | nodeName: node.name,
2897 | message: issue.message
2898 | });
2899 | } else if (issue.severity === 'warning') {
2900 | result.warnings.push({
2901 | type: 'warning',
2902 | nodeId: node.id,
2903 | nodeName: node.name,
2904 | message: issue.message
2905 | });
2906 | }
2907 | // Skip 'info' level issues for now
2908 | }
2909 |
2910 | // Generic check: Tool should be connected to AI Agent
2911 | if (normalizedType.startsWith('@n8n/n8n-nodes-langchain.tool')) {
2912 | const outgoing = workflow.connections[node.name];
2913 | if (!outgoing?.ai_tool || outgoing.ai_tool.flat().filter(c => c).length === 0) {
2914 | result.warnings.push({
2915 | type: 'warning',
2916 | nodeId: node.id,
2917 | nodeName: node.name,
2918 | message: `Tool node "${node.name}" is not connected to any AI Agent via ai_tool output.`
2919 | });
2920 | }
2921 | }
2922 | }
2923 | }
2924 | ```
2925 |
2926 | ## Summary: Validation Coverage
2927 |
2928 | ✅ **Complete Coverage**:
2929 | - AI Agent (required connections, streaming mode, prompt type)
2930 | - Basic LLM Chain (required connections, forbidden connections)
2931 | - Chat Trigger (response mode, downstream compatibility)
2932 | - All 13 AI tool sub-nodes with specific validation rules
2933 |
2934 | ✅ **Connection Direction Enforcement**:
2935 | - Reverse connection mapping to validate incoming connections
2936 | - Proper validation of ai_languageModel, ai_memory, ai_tool, etc.
2937 |
2938 | ✅ **Tool-Specific Rules**:
2939 | - HTTP Request Tool: Placeholder validation
2940 | - Code Tool: Function name and schema validation
2941 | - Vector Store Tool: Complete chain validation (Tool → VectorStore → Embedding)
2942 | - Workflow Tool: Sub-workflow existence
2943 | - Search Tools: Credential validation
2944 | - AI Agent Tool: Nested agent validation
2945 | - MCP Client Tool: Server configuration validation
2946 |
2947 | ## Database Coverage Summary
2948 |
2949 | ### What We Have in Our Database ✅
2950 |
2951 | 1. **All Purpose-Built AI Tool Sub-Nodes** (13 nodes)
2952 | - Tool HTTP Request, Tool Code, Tool Workflow, Tool Vector Store
2953 | - Tool Calculator, Tool Wikipedia, Tool SerpAPI, Tool SearXNG
2954 | - Tool WolframAlpha, Tool Think
2955 | - AI Agent Tool, MCP Client Tool, Tool Executor
2956 |
2957 | 2. **All AI Components** (21 nodes from @n8n/n8n-nodes-langchain)
2958 | - AI Agent, Basic LLM Chain
2959 | - All LLM nodes (OpenAI, Anthropic, Google Gemini, Cohere, etc.)
2960 | - All Embedding nodes (OpenAI, Azure, Cohere, HuggingFace)
2961 | - All Chain nodes (QA Chain, Summarization Chain)
2962 | - Memory nodes, Vector Store nodes, Document Loaders, etc.
2963 |
2964 | 3. **All Regular Nodes Usable as Tools** (248 nodes from n8n-nodes-base)
2965 | - Complete access to node metadata (type, properties, operations, credentials)
2966 | - Can validate: Airtable, Slack, HTTP Request, Google Sheets, MySQL, PostgreSQL, etc.
2967 | - Can check: Required parameters, credentials, operation modes
2968 |
2969 | ### Validation Capabilities by Node Type
2970 |
2971 | | Node Category | Count | Validation Level |
2972 | |---------------|-------|------------------|
2973 | | **Purpose-Built Tool Nodes** | 13 | ⭐⭐⭐ **Specific** (custom validation per tool) |
2974 | | **AI Agent & Chains** | 5 | ⭐⭐⭐ **Specific** (connection type enforcement) |
2975 | | **LLM & Embedding Nodes** | 16 | ⭐⭐ **Medium** (generic AI component validation) |
2976 | | **Regular Nodes as Tools** | 248 | ⭐⭐ **Medium** (generic tool validation + node config) |
2977 |
2978 | ### What We Can Validate
2979 |
2980 | ✅ **Connection Architecture**:
2981 | - All 8 AI connection types (ai_languageModel, ai_memory, ai_tool, etc.)
2982 | - Connection direction enforcement (connections flow TO AI Agent)
2983 | - Reverse connection mapping
2984 | - Streaming mode constraints
2985 |
2986 | ✅ **Purpose-Built Tool Nodes** (13 nodes with specific rules):
2987 | - HTTP Request Tool: Placeholder validation
2988 | - Code Tool: Function name, input schema validation
2989 | - Vector Store Tool: Complete chain validation (vectorStore → embedding)
2990 | - Workflow Tool: Sub-workflow reference validation
2991 | - Search Tools: Credential validation
2992 | - All others with appropriate rules
2993 |
2994 | ✅ **Regular Nodes as Tools** (248 nodes):
2995 | - Node type lookup from database
2996 | - Property validation using node schema
2997 | - Credential requirement checking
2998 | - Operation/resource mode validation
2999 | - Tool description recommendations
3000 |
3001 | ✅ **AI Agent Workflows**:
3002 | - Required ai_languageModel connection
3003 | - Optional ai_memory, ai_tool, ai_outputParser connections
3004 | - Chat Trigger integration (streaming mode, prompt type)
3005 | - Tool connectivity and descriptions
3006 |
3007 | ✅ **Basic LLM Chain Workflows**:
3008 | - Required ai_languageModel connection
3009 | - Forbidden ai_memory and ai_tool connections
3010 | - Optional ai_outputParser connection
3011 |
3012 | ### Implementation Priority
3013 |
3014 | **Phase 1: Core Infrastructure** ✅
3015 | - [x] Document complete AI tool ecosystem (269 nodes)
3016 | - [ ] Update `WorkflowConnection` interface with all AI connection types
3017 | - [ ] Implement `buildReverseConnectionMap()` utility
3018 | - [ ] Add helper functions for node type checking
3019 |
3020 | **Phase 2: AI Agent & Chain Validation** (CRITICAL)
3021 | - [ ] Implement `validateAIAgent()` with:
3022 | - Required ai_languageModel check
3023 | - Streaming mode validation
3024 | - Prompt type compatibility
3025 | - Tool connection validation
3026 | - [ ] Implement `validateBasicLLMChain()` with:
3027 | - Required ai_languageModel check
3028 | - Forbidden connection checks
3029 | - [ ] Implement `validateChatTrigger()` with:
3030 | - Response mode compatibility
3031 | - Downstream node validation
3032 |
3033 | **Phase 3: Purpose-Built Tool Validation** (HIGH PRIORITY)
3034 | - [ ] Implement `validateHTTPRequestTool()` with placeholder checking
3035 | - [ ] Implement `validateCodeTool()` with schema validation
3036 | - [ ] Implement `validateVectorStoreTool()` with chain validation
3037 | - [ ] Implement `validateWorkflowTool()` with reference checking
3038 | - [ ] Implement `validateSearchTool()` with credential checking
3039 | - [ ] Implement remaining tool-specific validators
3040 |
3041 | **Phase 4: Generic Tool Validation** (MEDIUM PRIORITY)
3042 | - [ ] Implement generic tool connection validator
3043 | - [ ] Validate tool descriptions (toolDescription or description field)
3044 | - [ ] Check credentials configured for regular nodes used as tools
3045 | - [ ] Validate node parameters using database schema
3046 |
3047 | **Phase 5: Testing & Documentation**
3048 | - [ ] Write unit tests for each validation function
3049 | - [ ] Write integration tests with real workflow templates (2985, 3680, 5296)
3050 | - [ ] Test with all 13 purpose-built tool nodes
3051 | - [ ] Test with sample regular nodes as tools (Slack, HTTP Request, Airtable)
3052 | - [ ] Update validation documentation
3053 | - [ ] Add MCP tool examples for validation checking
3054 |
3055 | ## Implementation Checklist
3056 |
3057 | ### Core Infrastructure ✅
3058 | - [ ] Update `WorkflowConnection` interface with all AI connection types
3059 | - [ ] Implement `buildReverseConnectionMap()` utility
3060 | - [ ] Add helper functions for node type checking
3061 |
3062 | ### AI Agent Validation (Enhanced with Deep Understanding) 🎯
3063 | - [ ] Implement `validateAIAgent()` with:
3064 | - [x] **Prompt type validation** (auto vs define)
3065 | - [x] **Text field requirement** check (when promptType='define')
3066 | - [x] **Language model connection validation** (1 or 2 based on needsFallback)
3067 | - [x] **Fallback model validation** (needsFallback flag + 2 LLM connections)
3068 | - [x] **Output parser validation** (hasOutputParser flag + ai_outputParser connection)
3069 | - [x] **System message recommendations** (warn if missing)
3070 | - [x] **maxIterations validation** (warn if > 20)
3071 | - [x] **Version compatibility checks** (needsFallback requires v2.1+)
3072 | - [x] **Streaming mode validation** (Chat Trigger responseMode='streaming' → no main output)
3073 | - [ ] Memory connection validation (0-1 ai_memory)
3074 | - [ ] Tool connection validation (0-N ai_tool)
3075 |
3076 | ### Other AI Node Validation
3077 | - [ ] Implement `validateBasicLLMChain()`
3078 | - [ ] Implement `validateChatTrigger()`
3079 | - [ ] Implement `validateAllToolNodes()` with all 13 sub-validations
3080 | - [ ] Implement generic regular node as tool validation (248 nodes)
3081 |
3082 | ### Integration
3083 | - [ ] Add validation calls in main `validateWorkflow()` method
3084 | - [ ] Leverage database for node schema validation (269 nodes total)
3085 |
3086 | ### Testing
3087 | - [ ] Write unit tests for each validation function
3088 | - [ ] Write integration tests with real workflow templates (2985, 3680, 5296)
3089 |
3090 | ### Documentation
3091 | - [x] **Complete AI Agent deep architecture analysis**
3092 | - [x] **Document prompt construction (auto vs define)**
3093 | - [x] **Document system message patterns and best practices**
3094 | - [x] **Document fallback models feature**
3095 | - [x] **Document output parser integration**
3096 | - [x] **Document additional options (maxIterations, returnIntermediateSteps, etc.)**
3097 | - [x] **Document version differences (1.x vs 2.1+)**
3098 | - [x] **Provide real-world configuration examples**
3099 | - [x] **Specify MCP tool response improvements**
3100 | - [ ] Update MCP tool implementations to return enhanced information
3101 |
3102 | ## Key Insights for Implementation
3103 |
3104 | ### 1. AI Agent is NOT a Simple Node
3105 | The AI Agent node is the most complex node in n8n with:
3106 | - **2 prompt modes** (auto from Chat Trigger vs custom defined)
3107 | - **Dynamic connection requirements** (1-2 LLMs based on fallback setting)
3108 | - **Critical system message** that defines entire behavior
3109 | - **Multiple optional enhancements** (memory, tools, output parsers)
3110 | - **Version-specific features** (fallback, output parser in v2.1+)
3111 | - **Streaming mode constraints** (no main output when Chat Trigger streams)
3112 |
3113 | ### 2. Validation Must Be Context-Aware
3114 | Validation rules change based on:
3115 | - `promptType` setting → affects text field requirement
3116 | - `needsFallback` flag → affects LLM connection count requirement
3117 | - `hasOutputParser` flag → affects output parser connection requirement
3118 | - `typeVersion` → affects available features
3119 | - Upstream Chat Trigger's `responseMode` → affects downstream connection rules
3120 |
3121 | ### 3. System Message is the Most Important Field
3122 | - Defines agent's role, capabilities, constraints
3123 | - Controls tool usage behavior
3124 | - Specifies output format requirements
3125 | - Should be validated for completeness (warn if missing)
3126 | - Real-world templates show detailed, structured system messages
3127 |
3128 | ### 4. Fallback Models Are Production-Critical
3129 | - Automatic failover for reliability
3130 | - Rate limit mitigation
3131 | - Cost optimization strategies
3132 | - Must validate 2 LLM connections when enabled
3133 |
3134 | ### 5. Output Parsers Enforce Structure
3135 | - JSON/XML schema validation
3136 | - Required for structured data extraction
3137 | - System message should define format, parser enforces it
3138 | - Must validate connection when flag is set
3139 |
3140 | ### 6. MCP Tools Need Enhancement
3141 | Current MCP tools should return:
3142 | - **Prompt configuration details** (auto vs define modes)
3143 | - **System message importance and best practices**
3144 | - **Fallback model feature documentation**
3145 | - **Output parser integration patterns**
3146 | - **Connection requirement matrix**
3147 | - **Common configuration mistakes**
3148 | - **Real-world usage examples from templates**
3149 |
3150 | ## Implementation Pseudo-Code
3151 |
3152 | ### Core Utility: Build Reverse Connection Map
3153 |
3154 | ```typescript
3155 | /**
3156 | * Builds a reverse connection map to find what connects TO each node
3157 | * This is CRITICAL for validating AI nodes since connections flow TO them
3158 | */
3159 | function buildReverseConnectionMap(workflow: WorkflowJson): Map<string, ReverseConnection[]> {
3160 | const map = new Map<string, ReverseConnection[]>();
3161 |
3162 | for (const [sourceName, outputs] of Object.entries(workflow.connections)) {
3163 | const sourceNode = workflow.nodes.find(n => n.name === sourceName);
3164 | const sourceType = sourceNode ? NodeTypeNormalizer.normalizeToFullForm(sourceNode.type) : '';
3165 |
3166 | // Iterate through all connection types (main, error, ai_*)
3167 | for (const [outputType, connections] of Object.entries(outputs)) {
3168 | if (!Array.isArray(connections)) continue;
3169 |
3170 | for (const connArray of connections) {
3171 | if (!Array.isArray(connArray)) continue;
3172 |
3173 | for (const conn of connArray) {
3174 | if (!conn) continue;
3175 |
3176 | // Add to reverse map
3177 | if (!map.has(conn.node)) {
3178 | map.set(conn.node, []);
3179 | }
3180 | map.get(conn.node)!.push({
3181 | sourceName,
3182 | sourceType,
3183 | type: outputType,
3184 | index: conn.index
3185 | });
3186 | }
3187 | }
3188 | }
3189 | }
3190 |
3191 | return map;
3192 | }
3193 |
3194 | interface ReverseConnection {
3195 | sourceName: string;
3196 | sourceType: string;
3197 | type: string; // 'main', 'ai_languageModel', 'ai_tool', etc.
3198 | index: number;
3199 | }
3200 | ```
3201 |
3202 | ### Main Validation Flow
3203 |
3204 | ```typescript
3205 | /**
3206 | * Main entry point for AI node validation
3207 | */
3208 | function validateAINodes(
3209 | workflow: WorkflowJson,
3210 | result: WorkflowValidationResult
3211 | ): void {
3212 | // Build reverse connection map
3213 | const reverseConnections = buildReverseConnectionMap(workflow);
3214 |
3215 | for (const node of workflow.nodes) {
3216 | if (node.disabled || isStickyNote(node)) continue;
3217 |
3218 | const normalizedType = NodeTypeNormalizer.normalizeToFullForm(node.type);
3219 |
3220 | // Route to appropriate validator
3221 | if (normalizedType === '@n8n/n8n-nodes-langchain.agent') {
3222 | validateAIAgent(node, reverseConnections, workflow, result);
3223 | } else if (normalizedType === '@n8n/n8n-nodes-langchain.chainLlm') {
3224 | validateBasicLLMChain(node, reverseConnections, result);
3225 | } else if (normalizedType === '@n8n/n8n-nodes-langchain.chatTrigger') {
3226 | validateChatTrigger(node, workflow, result);
3227 | } else if (isToolNode(normalizedType)) {
3228 | validateToolNode(node, reverseConnections, workflow, result);
3229 | }
3230 | }
3231 | }
3232 |
3233 | function isToolNode(nodeType: string): boolean {
3234 | const toolNodeTypes = [
3235 | '@n8n/n8n-nodes-langchain.toolHttpRequest',
3236 | '@n8n/n8n-nodes-langchain.toolCode',
3237 | '@n8n/n8n-nodes-langchain.toolWorkflow',
3238 | '@n8n/n8n-nodes-langchain.toolVectorStore',
3239 | '@n8n/n8n-nodes-langchain.toolCalculator',
3240 | '@n8n/n8n-nodes-langchain.toolWikipedia',
3241 | '@n8n/n8n-nodes-langchain.toolSerpApi',
3242 | '@n8n/n8n-nodes-langchain.toolSearXng',
3243 | '@n8n/n8n-nodes-langchain.toolWolframAlpha',
3244 | '@n8n/n8n-nodes-langchain.toolThink',
3245 | '@n8n/n8n-nodes-langchain.agentTool',
3246 | '@n8n/n8n-nodes-langchain.mcpClientTool',
3247 | '@n8n/n8n-nodes-langchain.toolExecutor'
3248 | ];
3249 | return toolNodeTypes.includes(nodeType);
3250 | }
3251 | ```
3252 |
3253 | ### Complete AI Agent Validator
3254 |
3255 | ```typescript
3256 | function validateAIAgent(
3257 | node: WorkflowNode,
3258 | reverseConnections: Map<string, ReverseConnection[]>,
3259 | workflow: WorkflowJson,
3260 | result: WorkflowValidationResult
3261 | ): void {
3262 | const incoming = reverseConnections.get(node.name) || [];
3263 |
3264 | // 1. REQUIRED: ai_languageModel connection (1 or 2 if fallback)
3265 | const languageModelConnections = incoming.filter(c => c.type === 'ai_languageModel');
3266 |
3267 | if (node.parameters.needsFallback === true) {
3268 | if (languageModelConnections.length !== 2) {
3269 | result.errors.push({
3270 | type: 'error',
3271 | nodeId: node.id,
3272 | nodeName: node.name,
3273 | message: `AI Agent "${node.name}" has needsFallback=true but has ${languageModelConnections.length} language model connection(s). Exactly 2 are required (primary + fallback).`
3274 | });
3275 | }
3276 |
3277 | // Check version support
3278 | if (node.typeVersion < 2.1) {
3279 | result.errors.push({
3280 | type: 'error',
3281 | nodeId: node.id,
3282 | nodeName: node.name,
3283 | message: `AI Agent "${node.name}" uses needsFallback but typeVersion ${node.typeVersion} does not support it. Upgrade to version 2.1+.`
3284 | });
3285 | }
3286 | } else {
3287 | if (languageModelConnections.length === 0) {
3288 | result.errors.push({
3289 | type: 'error',
3290 | nodeId: node.id,
3291 | nodeName: node.name,
3292 | message: `AI Agent "${node.name}" requires an ai_languageModel connection. Connect a language model node (e.g., OpenAI Chat Model, Google Gemini).`
3293 | });
3294 | } else if (languageModelConnections.length > 1) {
3295 | result.errors.push({
3296 | type: 'error',
3297 | nodeId: node.id,
3298 | nodeName: node.name,
3299 | message: `AI Agent "${node.name}" has ${languageModelConnections.length} ai_languageModel connections but needsFallback=false. Either enable fallback or keep only 1 language model.`
3300 | });
3301 | }
3302 | }
3303 |
3304 | // 2. Output parser validation
3305 | if (node.parameters.hasOutputParser === true) {
3306 | const outputParserConnections = incoming.filter(c => c.type === 'ai_outputParser');
3307 |
3308 | if (outputParserConnections.length === 0) {
3309 | result.errors.push({
3310 | type: 'error',
3311 | nodeId: node.id,
3312 | nodeName: node.name,
3313 | message: `AI Agent "${node.name}" has hasOutputParser=true but no ai_outputParser connection. Connect an Output Parser node.`
3314 | });
3315 | } else if (outputParserConnections.length > 1) {
3316 | result.warnings.push({
3317 | type: 'warning',
3318 | nodeId: node.id,
3319 | nodeName: node.name,
3320 | message: `AI Agent "${node.name}" has ${outputParserConnections.length} output parser connections. Only the first will be used.`
3321 | });
3322 | }
3323 | }
3324 |
3325 | // 3. Prompt type validation
3326 | if (node.parameters.promptType === 'define') {
3327 | if (!node.parameters.text || node.parameters.text.trim() === '') {
3328 | result.errors.push({
3329 | type: 'error',
3330 | nodeId: node.id,
3331 | nodeName: node.name,
3332 | message: `AI Agent "${node.name}" has promptType="define" but the text field is empty. Provide a prompt or change to promptType="auto".`
3333 | });
3334 | }
3335 | } else if (node.parameters.promptType === 'auto') {
3336 | const chatTriggerInput = incoming.find(c =>
3337 | c.type === 'main' &&
3338 | c.sourceType === '@n8n/n8n-nodes-langchain.chatTrigger'
3339 | );
3340 |
3341 | if (!chatTriggerInput) {
3342 | result.warnings.push({
3343 | type: 'warning',
3344 | nodeId: node.id,
3345 | nodeName: node.name,
3346 | message: `AI Agent "${node.name}" has promptType="auto" but no Chat Trigger is connected. Either connect a Chat Trigger or change promptType to "define".`
3347 | });
3348 | }
3349 | }
3350 |
3351 | // 4. Streaming mode validation (CRITICAL)
3352 | const chatTriggerInput = incoming.find(c =>
3353 | c.type === 'main' &&
3354 | c.sourceType === '@n8n/n8n-nodes-langchain.chatTrigger'
3355 | );
3356 |
3357 | if (chatTriggerInput) {
3358 | const chatTriggerNode = workflow.nodes.find(n => n.name === chatTriggerInput.sourceName);
3359 | const responseMode = chatTriggerNode?.parameters?.options?.responseMode;
3360 |
3361 | if (responseMode === 'streaming') {
3362 | const outgoingMain = workflow.connections[node.name]?.main;
3363 | if (outgoingMain && outgoingMain.flat().some(c => c)) {
3364 | result.errors.push({
3365 | type: 'error',
3366 | nodeId: node.id,
3367 | nodeName: node.name,
3368 | message: `AI Agent "${node.name}" is connected from Chat Trigger with responseMode="streaming". It must NOT have outgoing main connections. The response streams back through the Chat Trigger.`
3369 | });
3370 | }
3371 | }
3372 | }
3373 |
3374 | // 5. System message recommendation
3375 | if (!node.parameters.options?.systemMessage) {
3376 | result.warnings.push({
3377 | type: 'warning',
3378 | nodeId: node.id,
3379 | nodeName: node.name,
3380 | message: `AI Agent "${node.name}" has no system message. Add one in options.systemMessage to define the agent's role, capabilities, and constraints.`
3381 | });
3382 | }
3383 |
3384 | // 6. maxIterations validation
3385 | const maxIterations = node.parameters.options?.maxIterations;
3386 | if (maxIterations !== undefined && maxIterations > 20) {
3387 | result.warnings.push({
3388 | type: 'warning',
3389 | nodeId: node.id,
3390 | nodeName: node.name,
3391 | message: `AI Agent "${node.name}" has maxIterations=${maxIterations}. High values may cause long execution times and high costs. Consider reducing to 20 or less.`
3392 | });
3393 | }
3394 |
3395 | // 7. Memory validation (optional, 0-1)
3396 | const memoryConnections = incoming.filter(c => c.type === 'ai_memory');
3397 | if (memoryConnections.length > 1) {
3398 | result.warnings.push({
3399 | type: 'warning',
3400 | nodeId: node.id,
3401 | nodeName: node.name,
3402 | message: `AI Agent "${node.name}" has ${memoryConnections.length} ai_memory connections. Only 1 is supported; additional connections will be ignored.`
3403 | });
3404 | }
3405 |
3406 | // 8. Tool validation
3407 | const toolConnections = incoming.filter(c => c.type === 'ai_tool');
3408 | for (const toolConn of toolConnections) {
3409 | const toolNode = workflow.nodes.find(n => n.name === toolConn.sourceName);
3410 | if (toolNode && !toolNode.parameters.toolDescription && !toolNode.parameters.description) {
3411 | result.warnings.push({
3412 | type: 'warning',
3413 | nodeId: toolNode.id,
3414 | nodeName: toolNode.name,
3415 | message: `Tool "${toolNode.name}" connected to AI Agent has no description. Add a toolDescription to help the LLM understand when to use this tool.`
3416 | });
3417 | }
3418 | }
3419 | }
3420 | ```
3421 |
3422 | ### Basic LLM Chain Validator
3423 |
3424 | ```typescript
3425 | function validateBasicLLMChain(
3426 | node: WorkflowNode,
3427 | reverseConnections: Map<string, ReverseConnection[]>,
3428 | result: WorkflowValidationResult
3429 | ): void {
3430 | const incoming = reverseConnections.get(node.name) || [];
3431 |
3432 | // 1. REQUIRED: ai_languageModel connection
3433 | const languageModelConnections = incoming.filter(c => c.type === 'ai_languageModel');
3434 | if (languageModelConnections.length === 0) {
3435 | result.errors.push({
3436 | type: 'error',
3437 | nodeId: node.id,
3438 | nodeName: node.name,
3439 | message: `Basic LLM Chain "${node.name}" requires an ai_languageModel connection. Connect a language model node.`
3440 | });
3441 | } else if (languageModelConnections.length > 1) {
3442 | result.warnings.push({
3443 | type: 'warning',
3444 | nodeId: node.id,
3445 | nodeName: node.name,
3446 | message: `Basic LLM Chain "${node.name}" has ${languageModelConnections.length} ai_languageModel connections. Only 1 is supported.`
3447 | });
3448 | }
3449 |
3450 | // 2. FORBIDDEN: ai_memory connections
3451 | const memoryConnections = incoming.filter(c => c.type === 'ai_memory');
3452 | if (memoryConnections.length > 0) {
3453 | result.errors.push({
3454 | type: 'error',
3455 | nodeId: node.id,
3456 | nodeName: node.name,
3457 | message: `Basic LLM Chain "${node.name}" does not support ai_memory connections. Use AI Agent instead if you need conversation memory.`
3458 | });
3459 | }
3460 |
3461 | // 3. FORBIDDEN: ai_tool connections
3462 | const toolConnections = incoming.filter(c => c.type === 'ai_tool');
3463 | if (toolConnections.length > 0) {
3464 | result.errors.push({
3465 | type: 'error',
3466 | nodeId: node.id,
3467 | nodeName: node.name,
3468 | message: `Basic LLM Chain "${node.name}" does not support ai_tool connections. Use AI Agent instead if you need tool calling.`
3469 | });
3470 | }
3471 |
3472 | // 4. OPTIONAL: ai_outputParser connection (0-1)
3473 | const outputParserConnections = incoming.filter(c => c.type === 'ai_outputParser');
3474 | if (outputParserConnections.length > 1) {
3475 | result.warnings.push({
3476 | type: 'warning',
3477 | nodeId: node.id,
3478 | nodeName: node.name,
3479 | message: `Basic LLM Chain "${node.name}" has ${outputParserConnections.length} output parser connections. Only 1 is supported.`
3480 | });
3481 | }
3482 | }
3483 | ```
3484 |
3485 | ## Next Steps
3486 |
3487 | 1. **Implement Enhanced AI Agent Validator** using the complete specification from this document
3488 | 2. **Update MCP Tool Responses** to include AI Agent deep understanding
3489 | 3. **Test with Real Templates** (2985, 3680, 5296) to validate correctness
3490 | 4. **Extend to Other AI Nodes** (Basic LLM Chain, Chat Trigger, Tools)
3491 | 5. **Complete 269-Node Validation Coverage** for all tool nodes
3492 |
```