# Tool Reference

All tools the Instance AI agent has access to. Tools are organized into
orchestration tools (used by the orchestrator for loop control) and domain tools
(used by the orchestrator directly). Each tool defines
its input/output schema via Zod.

## Orchestration Tools

These tools are exclusive to the orchestrator agent. Sub-agents do not receive
them. Some are conditional on context availability.

### `create-tasks`

Persist a dependency-aware task plan for detached multi-step execution. For
initial plan-worthy work, the orchestrator loads the `planning` skill, performs
discovery with normal domain tools, then calls `create-tasks` with
`planningContext.source: "planning-skill"`. For
`<planned-task-follow-up type="replan">` turns, use
`planningContext.source: "replan"` when multiple dependent tasks still need
scheduling. Clear single-workflow builds, including new and one-off workflows,
use `workflow-builder`, workspace file tools, and `build-workflow` directly.
The plan is shown to the user for approval before execution starts.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tasks` | array | yes | Dependency-aware execution plan (see schema below) |
| `planningContext` | object | yes | `{ source: "planning-skill" \| "replan", summary: string, assumptions?: string[] }` |

**Task schema**:

```typescript
{
  id: string;          // Stable identifier used by dependency edges
  title: string;       // Short user-facing task title
  kind: 'build-workflow' | 'checkpoint';
  spec: string;        // Detailed executor briefing for this task
  deps: string[];      // Task IDs that must succeed before this task can start
  workflowId?: string; // Existing workflow ID for the builder to hydrate before saving
  isSupportingWorkflow?: boolean; // Build task completes after saving a supporting sub-workflow
}
```

**Returns**: `{ result: string, taskCount: number }`

**Behavior**:
- First call persists the plan, publishes `tasks-update` event, and **suspends**
  for user approval
- On approval: calls `schedulePlannedTasks()` to start detached execution
- On rejection: returns feedback for the LLM to revise the plan
- On denial: cancels the graph and blocks same-turn resubmission

**Task kinds** map to executors:
- `build-workflow` → orchestrator follow-up run using the workflow-builder skill
- `checkpoint` → exceptional orchestrator-executed semantic or cross-workflow check

Standalone data-table work is handled directly by the orchestrator with the
`data-table-manager` skill and the `data-tables` / `parse-file` tools. Single
workflow-local table requirements belong in the builder task spec; plan only
when the table schema is shared, independently durable, or creates real
dependency coordination.

### `update-tasks`

Update a visible task checklist for the user. Used for lightweight progress
tracking during synchronous work.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tasks` | array | yes | List of `{id, description, status, detail?}` items |

**Returns**: `{ result: string }`

**Behavior**: Saves to storage, publishes `tasks-update` event for live UI refresh.

### `cancel-background-task` *(conditional)*

Cancel a running background task by its ID.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `taskId` | string | yes | Background task ID (from `<running-tasks>` context) |

**Returns**: `{ result: "Background task {taskId} cancelled." }`

**Cancellation flow** (three surfaces converge):
```
User clicks stop button  → POST /chat/:threadId/tasks/:taskId/cancel ─┐
User says "stop that"    → orchestrator calls cancel-background-task  ─┤
cancelRun (global stop)  → cancelBackgroundTasks(threadId)             ─┤
                                                                       ▼
                                           service.cancelBackgroundTask()
```

### `correct-background-task` *(conditional)*

Send a course correction to a running background task.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `taskId` | string | yes | Background task ID |
| `correction` | string | yes | Correction message |

**Returns**: `{ result: string }` — 'queued', 'task-completed', or 'task-not-found'

### `verify-built-workflow` *(conditional)*

Run a built workflow with per-execution pin data for verification (never
persisted to the workflow). Destructive and user-action nodes — write
operations, nodes with mocked credentials, mid-workflow Form pages, Wait
nodes — are **simulated**: the build outcome carries a per-node
execute-vs-simulate plan (`nodeSimulationPlan`, produced by a deterministic
classifier plus an LLM pass at submit time) and LLM-generated mock output
(`simulationFixtures`). Simulated nodes are pinned with their fixture, so
verification never sends messages, writes rows, deletes data, or parks in
`waiting`. The tool output marks simulated nodes (`simulatedNodes`,
`nodePreviews[].simulated`, `simulationNote`), and the saved execution
carries `resultData.simulation` so the editor can label simulated outputs.
For build outcomes that carry a plan, a `waiting` result is a failure (an
unsimulated user-action node); only legacy plan-less outcomes keep the
waiting-with-output-as-success fallback.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workItemId` | string | yes | Work item ID from build outcome |
| `workflowId` | string | yes | Workflow ID to execute |
| `inputData` | object | no   | Trigger payload — **shape depends on trigger type**, see below |
| `timeout` | number | no | Max wait in ms (default 300000) |

**`inputData` shape by trigger type** (the adapter's `getPinDataForTrigger` spreads or wraps based on type — passing the wrong shape produces null downstream values that look like an expression bug):

| Trigger | Pass | Adapter emits on `$json` |
|---|---|---|
| Form Trigger | flat field map, e.g. `{name: "Alice", email: "a@b.c"}` | `{ submittedAt, formMode: "instanceAi", name, email, ... }` — matches production. Do NOT wrap in `formFields`. |
| Webhook | body payload, e.g. `{event: "signup", userId: "..."}` | `{ headers, query, body: { event, userId, ... } }` |
| Chat Trigger | `{chatInput: "..."}` | `{ sessionId, action, chatInput }` |
| Schedule | omit | synthetic timestamp fields |

**Writes on success/failure**: the tool persists a structured `verification`
record (`{ attempted, success, executionId, status, evidence, verifiedAt }`) onto
the build outcome so workflow-verification follow-ups and exceptional checkpoint
turns can reuse it without re-running verify.

**Returns**: `{ executionId?, success, status?, data?, error? }`

### `report-verification-verdict` *(conditional)*

Feed verification results into the deterministic workflow loop state machine.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workItemId` | string | yes | Work item ID |
| `verdict` | enum | yes | `verified`, `needs_patch`, `needs_rebuild`, `trigger_only`, `needs_user_input`, `failed_terminal` |
| `failureSignature` | string | no | For repeated failure detection |
| `failedNodeName` | string | no | Node that failed |
| `patch` | string | no | For `needs_patch` verdict |
| `diagnosis` | string | no | Failure analysis |

**Returns**: `{ guidance: string }` — next action based on loop state machine.

### `apply-workflow-credentials` *(conditional)*

Atomically apply real credentials to previously-mocked workflow nodes.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workItemId` | string | yes | Work item ID from build outcome |
| `credentials` | object | yes | Real credential mapping |

**Returns**: `{ updatedNodes: string[] }`

## Workflow Tools (10–14)

Core count is 10; up to 4 more are conditionally registered based on license.

### `list-workflows`

List workflows accessible to the current user.

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `query` | string | no | — | Filter workflows by name |
| `limit` | number | no | 50 | Max results (1–100) |
| `status` | `"active" \| "archived" \| "all"` | no | `"active"` | Which workflows to list |

**Returns**: `{ workflows: [{ id, name, activeVersionId, isArchived, createdAt, updatedAt }] }`

`activeVersionId` is `null` when the workflow is unpublished.

### `get-workflow`

Get full workflow definition including nodes, connections, and settings.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workflowId` | string | yes | Workflow ID |

**Returns**: `{ id, name, activeVersionId, isArchived, nodes, connections, settings }`

`activeVersionId` is `null` when the workflow is unpublished.

### `get-workflow-as-code`

Get a workflow as TypeScript SDK code. Used by the builder agent to inspect an
existing workflow when no workspace source file is already available. Existing
workflow modifications should write the returned code to a workspace source file
and call `build-workflow` with both `filePath` and the real n8n `workflowId`
once; subsequent repairs can reuse only `filePath`.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workflowId` | string | yes | Workflow ID |

**Returns**: TypeScript code string representing the workflow.

### `build-workflow`

Compile, validate, and save a workspace workflow source file. Inline source and
string patches are not accepted; edit the workspace file first and then call
this tool with `filePath`.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `filePath` | string | yes | Workspace path to the `.workflow.ts` or WorkflowJSON source file |
| `workflowId` | string | no | Existing n8n workflow ID to bind to this file on the first update |
| `projectId` | string | no | Project ID to create the workflow in |
| `name` | string | no | Workflow name override for new workflows |
| `workItemId` | string | no | Work item hint for workflow-loop reporting |
| `isSupportingWorkflow` | boolean | no | Marks a saved sub-workflow as supporting |

**Returns**: `{ success, workflowId?, workflowName?, workItemId?, filePath, sourceHash?, remediation?, errors?, warnings? }`

**Behavior**: Reads the source file from the runtime workspace, compiles
TypeScript sources through the sandbox `tsx` runner or parses WorkflowJSON
directly, validates the resulting workflow JSON server-side, resolves
credentials, saves by the workflow ID bound to the source file, and persists the
latest source hash and workflow version in thread metadata. If the file has no
saved workflow ID, the build creates a new workflow unless `workflowId` is
provided to bind the file to an existing workflow. If the bound workflow no
longer exists, the tool returns blocked remediation rather than creating a
replacement.

### `delete-workflow`

Archive a workflow (soft delete, deactivates if needed). This is reversible
with `unarchive-workflow`.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workflowId` | string | yes | Workflow to archive |

**Returns**: `{ success: boolean }`

### `unarchive-workflow`

Restore an archived workflow without publishing it.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workflowId` | string | yes | Archived workflow to restore |

**Returns**: `{ success: boolean }`

### `setup-workflow`

Open the UI for per-node credential and parameter setup. Uses a suspend/resume
state machine where each node triggers a HITL confirmation for the user to
configure it interactively.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workflowId` | string | yes | Workflow to set up |

**Returns**: `{ completedNodes, skippedNodes, failedNodes }`

### `publish-workflow`

Publish a workflow version to production. Makes it active — it will run on triggers.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workflowId` | string | yes | Workflow ID |
| `versionId` | string | no | Specific version (omit for latest draft) |

**Returns**: `{ success: boolean, activeVersionId?: string }`

### `unpublish-workflow`

Stop a workflow from running in production. The draft is preserved.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workflowId` | string | yes | Workflow ID |

**Returns**: `{ success: boolean }`

### `list-workflow-versions` *(conditional — requires license)*

List version history for a workflow (metadata only).

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `workflowId` | string | yes | — | Workflow ID |
| `limit` | number | no | 20 | Max results (1–100) |
| `skip` | number | no | 0 | Results to skip |

**Returns**: `{ versions: [{ versionId, name, description, authors, createdAt, autosaved, isActive, isCurrentDraft }] }`

### `get-workflow-version` *(conditional — requires license)*

Get full details of a specific workflow version including nodes and connections.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workflowId` | string | yes | Workflow ID |
| `versionId` | string | yes | Version ID |

**Returns**: `{ versionId, name, description, authors, nodes, connections, ... }`

### `restore-workflow-version` *(conditional — requires license)*

Restore a workflow to a previous version (overwrites current draft). HITL
approval required.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workflowId` | string | yes | Workflow ID |
| `versionId` | string | yes | Version to restore |

**Returns**: `{ success: boolean }`

### `update-workflow-version` *(conditional — requires `feat:namedVersions` license)*

Update a version's name or description.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workflowId` | string | yes | Workflow ID |
| `versionId` | string | yes | Version ID |
| `name` | string \| null | no | New name |
| `description` | string \| null | no | New description |

**Returns**: `{ success: boolean }`

---

## Execution Tools (6)

### `list-executions`

List recent workflow executions.

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `workflowId` | string | no | — | Filter by workflow |
| `status` | string | no | — | `success`, `error`, `running`, `waiting` |
| `limit` | number | no | 20 | Max results (1–100) |

**Returns**: `{ executions: [{ id, workflowId, workflowName, status, startedAt, finishedAt, mode }] }`

### `run-workflow`

Execute a workflow, wait for completion (with timeout), and return the result.
Default timeout: 5 minutes; max: 10 minutes. On timeout, execution is cancelled.

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `workflowId` | string | yes | — | Workflow to run |
| `inputData` | object | no | — | Data passed to the trigger node |
| `timeout` | number | no | 300000 | Max wait time in ms (max 600000) |

**Returns**: `{ executionId, status, data?, error?, startedAt?, finishedAt? }`

**Type-aware pin data**: Constructs proper pin data per trigger type:
- **Chat trigger**: `{ chatInput, sessionId, action }`
- **Form trigger**: `{ submittedAt, formMode: 'instanceAi', ...inputData }`
- **Webhook trigger**: `{ headers: {}, query: {}, body: inputData }`
- **Schedule trigger**: current datetime information
- **Unknown trigger**: `{ json: inputData }` (generic fallback)

### `get-execution`

Get execution status without blocking.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `executionId` | string | yes | Execution ID |

**Returns**: `{ executionId, status, data?, error?, startedAt?, finishedAt? }`

### `debug-execution`

Analyze a failed execution with structured diagnostics.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `executionId` | string | yes | Failed execution to debug |

**Returns**: `{ executionId, status, failedNode?: { name, type, error, inputData? }, nodeTrace: [{ name, type, status }] }`

### `get-node-output`

Get the output data of a specific node from an execution.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `executionId` | string | yes | Execution ID |
| `nodeName` | string | yes | Node name to get output for |

**Returns**: `{ nodeName, data?, error? }`

### `stop-execution`

Cancel a running execution.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `executionId` | string | yes | Execution to cancel |

**Returns**: `{ success: boolean, message: string }`

---

## Credential Tools (6)

> **Security note**: The agent never handles raw credential secrets. Credential
> creation and secret configuration is done through the n8n frontend UI (via
> `setup-credentials`) or Computer Use browser credential capture.

### `list-credentials`

List credentials accessible to the current user. Never exposes secrets.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | no | Filter by credential type (e.g., `notionApi`) |

**Returns**: `{ credentials: [{ id, name, type, createdAt, updatedAt }] }`

### `get-credential`

Get credential metadata. Never returns decrypted secrets.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `credentialId` | string | yes | Credential ID |

**Returns**: `{ id, name, type, createdAt, updatedAt, nodesWithAccess? }`

### `delete-credential`

Permanently delete a credential. **Irreversible** — HITL confirmation required.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `credentialId` | string | yes | Credential to delete |

**Returns**: `{ success: boolean }`

### `search-credential-types`

Search available credential types by name or description.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | yes | Search query (e.g., "slack", "oauth") |

**Returns**: `{ credentialTypes: [{ name, displayName, description }] }`

### `setup-credentials`

Open the credential picker UI for the user to configure credentials securely.
The LLM never sees secrets — the user interacts with the n8n frontend directly.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `credentialType` | string | yes | Credential type to set up |

**Returns**: `{ credentialId, credentialType, needsBrowserSetup? }`

**HITL**: Suspends execution and renders the credential setup UI. When
`needsBrowserSetup=true`, the orchestrator should load the
`credential-setup-with-computer-use` skill, use Computer Use `browser_*` tools
directly, then call `setup-credentials` again to finalize.

### `test-credential`

Test whether a credential is valid and can connect to its service.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `credentialId` | string | yes | Credential to test |

**Returns**: `{ success: boolean, message?: string }`

---

## Node Discovery Tools (6)

### `list-nodes`

List available node types in the n8n instance.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | no | Filter by name or description |

**Returns**: `{ nodes: [{ name, displayName, description, group, version }] }`

### `get-node-description`

Get detailed node description including properties, credentials, inputs, and outputs.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `nodeType` | string | yes | Node type (e.g., `n8n-nodes-base.httpRequest`) |

**Returns**: `{ name, displayName, description, properties, credentials, inputs, outputs }`

### `get-node-type-definition`

Get the full JSON schema for a node type, including all parameter options and
discriminators. Critical for understanding complex node configuration.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `nodeType` | string | yes | Node type |

**Returns**: Full node type definition with all parameters.

### `search-nodes`

Search nodes ranked by relevance with `@builderHint` annotations. Includes
subnode requirements and discriminator values.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | yes | Short search query (service names, not descriptions) |

**Returns**: `{ nodes: SearchableNodeDescription[] }`

### `get-suggested-nodes`

Get curated node suggestions for common use cases.

**Returns**: Categorized node suggestions with descriptions.

### `explore-node-resources`

Explore a node's dynamic resources (listSearch / loadOptions). Used to discover
discriminator values like spreadsheet IDs, calendar names, etc.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `nodeType` | string | yes | Node type |
| `resource` | string | yes | Resource to explore |
| `credentialId` | string | no | Credential to use for authenticated resources |

**Returns**: Dynamic resource list from the node's loadOptions/listSearch.

---

## Data Table Tools (11)

Full CRUD suite for n8n data tables. System columns (`id`, `createdAt`,
`updatedAt`) are reserved and auto-managed.

### Table operations

| Tool | Description |
|------|-------------|
| `list-data-tables` | List all data tables |
| `create-data-table` | Create a new data table with columns |
| `delete-data-table` | Delete a data table (HITL confirmation) |
| `get-data-table-schema` | Get table schema including all columns |

### Column operations

| Tool | Description |
|------|-------------|
| `add-data-table-column` | Add a column to a table |
| `delete-data-table-column` | Remove a column from a table |
| `rename-data-table-column` | Rename a column |

### Row operations

| Tool | Description |
|------|-------------|
| `query-data-table-rows` | Query rows with optional filters |
| `insert-data-table-rows` | Insert one or more rows |
| `update-data-table-rows` | Update rows matching criteria |
| `delete-data-table-rows` | Delete rows matching criteria (HITL confirmation) |

---

## Workspace Tools (up to 8, conditional)

Only registered when `workspaceService` is present. Folder tools additionally
require `workspaceService.listFolders`.

| Tool | Description |
|------|-------------|
| `list-projects` | List projects accessible to the user |
| `tag-workflow` | Apply tags to a workflow |
| `list-tags` | List available tags |
| `cleanup-test-executions` | Remove test execution data |
| `list-folders` | List folders (conditional) |
| `create-folder` | Create a new folder (conditional) |
| `delete-folder` | Delete a folder (conditional) |
| `move-workflow-to-folder` | Move a workflow to a folder (conditional) |

---

## Web Research Tools (2)

### `web-search` *(conditional — requires search provider)*

Search the web and return ranked results. Provider priority: Brave > SearXNG > disabled.

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `query` | string | yes | — | Search query |
| `maxResults` | number | no | 5 | Max results (1–20) |
| `includeDomains` | string[] | no | — | Restrict to these domains |

**Returns**: `{ query, results: [{ title, url, snippet, publishedDate? }] }`

Results cached for 15 minutes (LRU, 100 entries).

### `fetch-url`

Fetch a web page and extract content as markdown. Local pipeline (Readability +
Turndown). SSRF protection and result caching.

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `url` | string | yes | — | URL to fetch |
| `maxContentLength` | number | no | 30000 | Max content chars (max 100000) |

**Returns**: `{ url, finalUrl, title, content, truncated, contentLength, safetyFlags? }`

**Content routing**: HTML → Readability + Turndown + GFM, PDF → pdf-parse,
plain text / markdown → passthrough.

---

## Filesystem Tools (dynamic, conditional)

Only registered when a `localMcpServer` (computer-use gateway) is connected.
Tools are dynamically created from the MCP server's advertised capabilities.
See `docs/filesystem-access.md`.

---

## Knowledge Base (sandbox workspace)

Best-practices guides and curated workflow templates are materialized under
`<workspace_root>/knowledge-base/` when a builder sandbox is available. Agents
read them with workspace tools — there is no dedicated `get-best-practices` or
template-search tool.

| Path | Description |
|------|-------------|
| `knowledge-base/index.json` | Combined catalog of technique guides and curated templates |
| `knowledge-base/best-practices/index.json` | Catalog of workflow technique guides |
| `knowledge-base/best-practices/*.md` | Best-practices documentation per technique |
| `knowledge-base/templates/index.json` | Catalog of curated SDK workflow examples |
| `knowledge-base/templates/*.ts` | Template workflow source files |

Use `workspace_read_file` and `workspace_grep` (or shell equivalents in the
sandbox) to consult these before planning or building non-trivial workflows.

---

## Agent Builder Tool

### `agent_builder` *(conditional — requires the `agents` backend module)*

A single router tool that lets the assistant **create and configure an n8n
*Agent*** (the `AgentJsonConfig`: instructions, model, node/workflow/MCP/custom
tools, skills, tasks, integrations, sub-agents). It is registered as a **deferred**
tool and loaded on demand by the `agent-builder` skill; it is present only when the
`agents` module is enabled (and the skill is only offered when the sandbox
workspace is available, since config edits go through workspace files). All
builder capabilities are exposed as `action`s on this one tool. See
`docs/agent-builder.md` for the design.

Config mutations are file-based: the assistant writes the agent config JSON to
a workspace file (`src/agents/<slug>.agent.json`), edits it with the normal
file tools, and persists it with `build_agent` — mirroring how workflow builds
consume `.workflow.ts` sources. Validation stays host-side; the workspace is
only the file medium.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `action` | string | yes | Which builder action to run (see below) |
| …action fields | — | — | Each action carries its own fields (validated per action on dispatch) |

**Returns**: shape depends on the action — typically `{ ok: true, … }` on success or
`{ ok: false, errors: [{ path?, message }] }` on failure.

**Actions**:

| Action | Description |
|--------|-------------|
| `create_agent` | Create a new empty agent and bind the conversation to it. Call this first when no agent is targeted yet. |
| `read_config` | Read the current agent config plus freshness metadata (`configHash`, `updatedAt`, `versionId`). Call before every `build_agent`; use its `config` to (re)materialize the config file. |
| `build_agent` | Validate and persist the agent config from a workspace JSON file (`filePath`). Validates the schema, rejects empty instructions and unsupported native web search, enforces no `$fromAI` on stable dynamic selectors, and normalizes native web-search provider tools. Requires `baseConfigHash` (stale-write guard) and the runtime workspace. |
| `search_nodes` | Search the node catalog for **agent-tool-capable** nodes (excludes triggers/hidden/HITL) to add as node tools. |
| `get_node_types` | Get TypeScript type definitions for node types — exact parameter names, enums, credential types, and `@searchListMethod`/`@loadOptionsMethod`/`@builderHint` annotations. |
| `get_resource_locator_options` | Resolve live options for a parameter behind a `resourceLocator` / `loadOptionsMethod` / `loadOptions` routing (stable IDs like Linear teamId, Slack channel, model). Returns each option's `parameterValue` to write into `nodeParameters` (instead of `$fromAI`). |
| `create_skill` | Create a reusable, load-on-demand target-agent skill (name + routing description + structured body). Does not attach it — add the `{ type: "skill", id }` ref in the config file and `build_agent`. |
| `create_task` | Create a recurring scheduled task (name + objective + cron) for the target agent. Adds a `{ type: "task" }` ref to the config. |
| `build_custom_tool` | Compile and store a custom TypeScript tool (`export default new Tool(...)`), sandbox-validated. Register it by adding `{ type: "custom", id }` to `tools` in the config file and calling `build_agent`. |
| `list_integration_types` | List chat-platform integration types with their supported credential types and builder guidance. |
| `list_sub_agents` | List published same-project agents that can be attached as sub-agents. |
| `list_agents` | List every agent in the target agent’s project (no published-only filter; use to discover agents to edit or see what exists). |
| `list_workflows` | List workflows attachable as `type: "workflow"` tools (supported trigger types only). |
| `search_mcp_servers` | Search the MCP registry for servers to attach (returns url, transport, auth, credential type, tools). |
| `verify_mcp_server` | Test connectivity to an MCP server and list its tools before adding it to the config. |
| `resolve_llm` | Resolve the agent's main LLM (provider/model/credential) non-interactively; returns `ok: false` with candidates when the choice is missing/ambiguous. |

**Getting user input:** `configure_channel` is the only builder-specific interactive
card — it renders the chat-channel setup UI inline in the chat so the user creates
a new credential and connects (or skips) a channel. For every other user input (a
choice, which credential, which model), use the native `ask-user` tool. Non-channel
credentials are listed via the native `credentials` tool (`action: "list"`; +
`ask-user` when several match); the main LLM via `resolve_llm` (+ `ask-user`
fallback), then written into the config file and persisted with `build_agent`.

**`configure_channel`** *(standalone, not a router action)*: interactive HITL tool
that opens the agent chat-channel setup UI. Takes `{ integrationType }` (from
`list_integration_types`; unsupported types are rejected). Suspends the run,
renders the setup UI, and resumes with `{ connected: boolean }` — `false` means
the user skipped, do not re-prompt. The setup UI persists the connection itself;
do **not** call the `credentials` tool for a channel and do **not** write channel
entries into `integrations`.

**Targeting:** actions that mutate a specific agent require a bound agent; before one
exists they return a structured error telling the model to `create_agent` first.
`create_agent` is target-less; it binds the run to the new agent and persists the
binding in thread metadata so follow-up turns keep editing the same agent.

## Other Domain Tools

| Tool | Description |
|------|-------------|
| `ask-user` | Suspend and request user input (single/multi-select or text) |

---

## Tool Distribution

The orchestrator has access to the full native and orchestration surface.
Specialized background agents (for example `eval-setup-with-agent`) receive
only the domain tools wired into that agent.

| Tool Category | Orchestrator | Specialized background agents |
|---------------|:---:|:---:|
| Orchestration tools (`create-tasks`, etc.) | ✅ | ❌ |
| Workflow tools | ✅ | ✅ (eval-setup) |
| Execution tools | ✅ | ❌ |
| Credential tools | ✅ | ✅ (eval-setup — setup only) |
| Node discovery tools | ✅ | ✅ (eval-setup) |
| Data table tools | ✅ (direct, via `data-table-manager` skill) | ✅ (eval-setup) |
| Workspace tools | ✅ | ❌ |
| Filesystem tools | ✅ (conditional) | ❌ |
| Web research tools | ✅ | ❌ |
| Knowledge base (best practices & templates via workspace) | ✅ | ✅ (eval-setup) |
| Sandbox-backed internals (`build-workflow` TypeScript compilation, `materialize-node-type`) | ✅ | ❌ |
| MCP tools | ✅ | ❌ |
| Computer Use browser tools | ✅ (direct, via credential skill when setting up credentials) | ❌ |

---

## Adding New Tools

1. Create a file in `src/tools/<domain>/` following the naming convention `<verb>-<noun>.tool.ts`
2. Define input/output schemas with Zod (`.describe()` on fields — these are the LLM's parameter docs)
3. Export a factory function that takes the service context and returns an `@n8n/agents` tool
4. Register the tool in `src/tools/index.ts` (in `createAllTools` or `createOrchestrationTools`)
5. If the tool requires a new service method, add it to the interface in `src/types.ts`
   and implement it in the backend adapter
6. New native domain tools registered in `createAllTools` are available to the orchestrator immediately
7. For HITL tools, define `suspendSchema` and `resumeSchema` — `@n8n/agents` handles
   the suspension/resume lifecycle automatically