# Node Discovery Tools Guide

Complete guide for finding and understanding n8n nodes.

---

## search_nodes (START HERE!)

**Speed**: <20ms

**Use when**: You know what you're looking for (keyword, service, use case)

**Syntax**:
```javascript
search_nodes({
  query: "slack",      // Required: search keywords
  mode: "OR",          // Optional: OR (default), AND, FUZZY
  limit: 20,           // Optional: max results (default 20)
  source: "all",       // Optional: all, core, community, verified
  includeExamples: false  // Optional: include template configs
})
```

**Returns**:
```javascript
{
  "query": "slack",
  "results": [
    {
      "nodeType": "nodes-base.slack",                    // For search/validate tools
      "workflowNodeType": "n8n-nodes-base.slack",       // For workflow tools
      "displayName": "Slack",
      "description": "Consume Slack API",
      "category": "output",
      "relevance": "high"
    }
  ]
}
```

**Tips**:
- Common searches: webhook, http, database, email, slack, google, ai
- **Data-shaping phrases find the core node** (n8n-mcp 2.97.0+): a query that is only a phrase like "group by",
  "deduplicate", "flatten array", "rename fields", "compare lists", "join two lists", "sort items" or "format date"
  lists Summarize, Remove Duplicates, Split Out, Edit Fields, Compare Datasets, Merge, Sort or Date & Time first.
  Question words ("how to …") are ignored. Add a service name ("hubspot deduplicate contacts") and results rank as usual.
  Search for the job before deciding a Code node is needed.
- `OR` mode (default): matches any word
- `AND` mode: requires all words
- `FUZZY` mode: typo-tolerant (finds "slak" → Slack)
- Use `source: "core"` for only built-in nodes
- Use `includeExamples: true` for real-world configs

---

## get_node (UNIFIED NODE INFORMATION)

The `get_node` tool provides all node information with different detail levels and modes.

### Detail Levels (mode="info")

| Detail | Tokens | Use When |
|--------|--------|----------|
| `minimal` | ~200 | Quick metadata check |
| `standard` | ~1-2K | **Most use cases (DEFAULT)** |
| `full` | ~3-8K | Complex debugging only |

### Standard Detail (RECOMMENDED)

**Speed**: <10ms | **Size**: ~1-2K tokens

**Use when**: You've found the node and need configuration details

```javascript
get_node({
  nodeType: "nodes-base.slack",      // Required: SHORT prefix format
  includeExamples: true              // Optional: get real template configs
})
// detail="standard" is the default
```

**Returns**:
- Available operations and resources
- Essential properties (10-20 most common), resolved for the node's current typeVersion
- The settings inside `options` collections and fixedCollections (n8n-mcp 2.97.0+): name + one line, with the
  nested field names, the allowed values, and when the setting applies (`Only when operation=formatDate.`). This is
  where pagination, batching, raw body, Merge combine settings and similar Code-replacing options show up. A list cut
  at 25 settings says so; use `search_properties` or `detail: "full"` for the rest.
- Metadata (isAITool, isTrigger, hasCredentials)
- Real examples from templates (if includeExamples: true)

Option-heavy nodes are larger since 2.97.0 (HTTP Request ~5.5 KB, Merge ~5 KB, Webhook ~4.6 KB); most nodes are unchanged.

### Minimal Detail

**Speed**: <5ms | **Size**: ~200 tokens

**Use when**: Just need basic metadata

```javascript
get_node({
  nodeType: "nodes-base.slack",
  detail: "minimal"
})
```

**Returns**: nodeType, displayName, description, category

### Full Detail (USE SPARINGLY)

**Speed**: <100ms | **Size**: ~3-8K tokens

**Use when**: Debugging complex configuration, need complete schema

```javascript
get_node({
  nodeType: "nodes-base.httpRequest",
  detail: "full"
})
```

**Warning**: Large payload! Use `standard` for most cases.

---

## get_node Modes

### mode="docs" (READABLE DOCUMENTATION)

**Use when**: Need human-readable documentation with examples

```javascript
get_node({
  nodeType: "nodes-base.slack",
  mode: "docs"
})
```

**Returns**: Formatted markdown with:
- Usage examples
- Authentication guide
- Common patterns
- Best practices

**Better than raw schema for learning!**

### mode="search_properties" (FIND SPECIFIC FIELDS)

**Use when**: Looking for specific property in a node

```javascript
get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "search_properties",
  propertyQuery: "auth",           // Required for this mode
  maxPropertyResults: 20           // Optional: default 20
})
```

**Returns**: Property paths and descriptions matching query

**Common searches**: auth, header, body, json, url, method, credential

### mode="versions" (VERSION HISTORY)

**Use when**: Need to check node version history

```javascript
get_node({
  nodeType: "nodes-base.executeWorkflow",
  mode: "versions"
})
```

**Returns**: Version history with breaking changes flags

### mode="compare" (COMPARE VERSIONS)

**Use when**: Need to see differences between versions

```javascript
get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "compare",
  fromVersion: "3.0",
  toVersion: "4.1"       // Optional: defaults to latest
})
```

**Returns**: Property-level changes between versions

### mode="breaking" (BREAKING CHANGES ONLY)

**Use when**: Checking for breaking changes before upgrades

```javascript
get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "breaking",
  fromVersion: "3.0"
})
```

**Returns**: Only breaking changes (not all changes)

### mode="migrations" (AUTO-MIGRATABLE)

**Use when**: Checking what can be auto-migrated

```javascript
get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "migrations",
  fromVersion: "3.0"
})
```

**Returns**: Changes that can be automatically migrated

---

## Additional Parameters

### includeTypeInfo

Add type structure metadata (validation rules, JS types)

```javascript
get_node({
  nodeType: "nodes-base.if",
  includeTypeInfo: true   // Adds ~80-120 tokens per property
})
```

Use for complex nodes like filter, resourceMapper

### includeExamples

Include real-world configuration examples from templates

```javascript
get_node({
  nodeType: "nodes-base.slack",
  includeExamples: true   // Adds ~200-400 tokens per example
})
```

Only works with `mode: "info"` and `detail: "standard"`

---

## Common Workflow: Finding & Configuring

```
Step 1: Search
search_nodes({query: "slack"})
→ Returns: nodes-base.slack

Step 2: Get Operations (18s avg thinking time)
get_node({
  nodeType: "nodes-base.slack",
  includeExamples: true
})
→ Returns: operations list + example configs

Step 3: Validate Config
validate_node({
  nodeType: "nodes-base.slack",
  config: {resource: "channel", operation: "create"},
  profile: "runtime"
})
→ Returns: validation result

Step 4: Use in Workflow
(Configuration ready!)
```

**Most common pattern**: search → get_node (18s average)

---

## Quick Comparison

| Tool/Mode | When to Use | Speed | Size |
|-----------|-------------|-------|------|
| `search_nodes` | Find by keyword | <20ms | Small |
| `get_node (standard)` | **Get config (DEFAULT)** | <10ms | 1-2K |
| `get_node (minimal)` | Quick metadata | <5ms | 200 |
| `get_node (full)` | Complex debugging | <100ms | 3-8K |
| `get_node (docs)` | Learn usage | Fast | Medium |
| `get_node (search_properties)` | Find specific field | Fast | Small |
| `get_node (versions)` | Check versions | Fast | Small |

**Best Practice**: search → get_node(standard) → validate

---

## nodeType Format (CRITICAL!)

**Search/Validate Tools** (SHORT prefix):
```javascript
"nodes-base.slack"
"nodes-base.httpRequest"
"nodes-langchain.agent"
```

**Workflow Tools** (FULL prefix):
```javascript
"n8n-nodes-base.slack"
"n8n-nodes-base.httpRequest"
"@n8n/n8n-nodes-langchain.agent"
```

**Conversion**: search_nodes returns BOTH formats:
```javascript
{
  "nodeType": "nodes-base.slack",          // Use with get_node, validate_node
  "workflowNodeType": "n8n-nodes-base.slack"  // Use with n8n_create_workflow
}
```

---

## Examples

### Find and Configure HTTP Request

```javascript
// Step 1: Search
search_nodes({query: "http request"})

// Step 2: Get standard info
get_node({nodeType: "nodes-base.httpRequest"})

// Step 3: Find auth options
get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "search_properties",
  propertyQuery: "authentication"
})

// Step 4: Validate config
validate_node({
  nodeType: "nodes-base.httpRequest",
  config: {method: "POST", url: "https://api.example.com"},
  profile: "runtime"
})
```

### Explore AI Nodes

```javascript
// Find all AI-related nodes
search_nodes({query: "ai agent", source: "all"})

// Get AI Agent documentation
get_node({nodeType: "nodes-langchain.agent", mode: "docs"})

// Get configuration details with examples
get_node({
  nodeType: "nodes-langchain.agent",
  includeExamples: true
})
```

### Check Version Compatibility

```javascript
// See all versions
get_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})

// Check breaking changes from v1 to v2
get_node({
  nodeType: "nodes-base.executeWorkflow",
  mode: "breaking",
  fromVersion: "1.0"
})
```

---

## Related

- [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Validate node configs
- [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) - Use nodes in workflows