> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-docs.synta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Tips and tricks for building better n8n workflows with AI

Get the most out of Synta MCP with these proven strategies for workflow building, debugging, and optimization.

## Workflow Building Strategies

<CardGroup cols="2">
  <Card title="Use Plan Mode" icon="brain">
    In Cursor/Claude Code, use plan mode to break down complex workflow tasks into smaller, manageable steps before implementation.
  </Card>

  <Card title="Break Down Big Tasks" icon="list-check">
    Split large workflow projects into smaller tasks: node discovery → validation → building → testing. This improves accuracy and makes debugging easier.
  </Card>

  <Card title="Be Detailed in Requests" icon="message-lines">
    Specify exact node names, operations, parameters, and expected behavior. Clear, detailed requirements lead to better workflows and fewer iterations.
  </Card>

  <Card title="Start with Node Search" icon="magnifying-glass">
    Use `search_nodes({queries: ["your-node"]})` to find nodes (core & community) quickly.
  </Card>
</CardGroup>

## Discovery & Research

<Steps>
  <Step title="Search by Functionality">
    Start with a broad search to discover available nodes:

    ```
    search_nodes({queries: ["email"]})
    ```

    After you find the node you want, call `search_nodes(..., includeOperations: true)` if you need to see whether it exposes `resource`, `operation`, or `mode`. Use `get_node` with `includeConfigExamples: "json"` when you want real-world configurations.
  </Step>

  <Step title="Get Detailed Properties">
    Once you've identified a node, get its full property documentation:

    ```
    get_node({nodeIds: [{nodeId: "n8n-nodes-base.gmail"}], view: "standard"})
    ```

    Use `view: "standard"` before editing configuration. If `search_nodes(..., includeOperations: true)` returned `resource`, `operation`, or `mode`, include those exact values in `get_node(...)`.
  </Step>

  <Step title="Check Existing Templates">
    Look for proven patterns in the template library:

    ```
    search_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.gmail"]})
    ```

    Templates show real-world implementations you can learn from or deploy directly.
  </Step>
</Steps>

<div class="callout mint-my-4 mint-px-4 mint-py-3 mint-overflow-hidden mint-rounded-xl mint-flex mint-gap-3 mint-border mint-border-[#c15f3c]/30 mint-bg-[#c15f3c]/10">
  <div class="mint-mt-0.5 mint-w-4 mint-flex-shrink-0">
    <svg class="mint-w-4 mint-h-4 mint-text-[#c15f3c]" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
      <path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" />
    </svg>
  </div>

  <div class="mint-text-sm mint-text-[#c15f3c]">
    <strong className="mint-text-[#c15f3c]">Template-first approach:</strong> Before building from scratch, check if a template exists. Templates are production-tested and save significant development time.
  </div>
</div>

## Validation & Testing

<Steps>
  <Step title="Validate Workflow Structure">
    Run validation to catch configuration errors:

    ```
    n8n_validate_workflow({id: "your-workflow-id"})
    ```

    This checks node configurations, connections, and expressions.
  </Step>

  <Step title="Auto-Fix Common Issues">
    Use autofix to automatically resolve common problems:

    ```
    n8n_autofix_workflow({id: "your-workflow-id", applyFixes: true})
    ```

    Preview fixes first with `applyFixes: false` (default).
  </Step>

  <Step title="Test with Self-Healing">
    Run the workflow with self-healing enabled:

    ```
    n8n_trigger_execution({id: "your-workflow-id"})
    n8n_manage_pindata({mode: "addPinData", id: "your-workflow-id", nodeName: "Webhook", pinData: [...]})
    ```

    AI automatically detects errors and modifies configurations to fix them. Use mock data to test without real webhooks or API calls.
  </Step>
</Steps>

<div class="callout mint-my-4 mint-px-4 mint-py-3 mint-overflow-hidden mint-rounded-xl mint-flex mint-gap-3 mint-border mint-border-[#c15f3c]/30 mint-bg-[#c15f3c]/10">
  <div class="mint-mt-0.5 mint-w-4 mint-flex-shrink-0">
    <svg class="mint-w-4 mint-h-4 mint-text-[#c15f3c]" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
      <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
    </svg>
  </div>

  <div class="mint-text-sm mint-text-[#c15f3c]">
    <strong className="mint-text-[#c15f3c]">Production Safety:</strong> Always test workflows in a development environment before deploying to production. Never edit production workflows directly without backups.
  </div>
</div>

## Debugging Workflows

When things go wrong, use these tools to debug:

<Steps>
  <Step title="Check Execution History">
    List recent executions to find failures:

    ```
    n8n_manage_executions({action: "list", workflowId: "your-id", status: "error"})
    ```
  </Step>

  <Step title="Get Error Details">
    Retrieve detailed error information:

    ```
    n8n_manage_executions({action: "get", id: "execution-id", mode: "error"})
    ```

    This includes the execution path leading to the error and upstream node data.
  </Step>

  <Step title="Correlate Multi-Workflow Executions">
    For complex systems with multiple workflows:

    ```
    n8n_manage_executions({action: "correlate", executionId: "starting-execution-id"})
    ```

    This traces execution chains across workflows using webhook path and timing analysis.
  </Step>
</Steps>

## Quick Reference

| Task                | Tool                    | Key Parameters                             |
| ------------------- | ----------------------- | ------------------------------------------ |
| Find nodes          | `search_nodes`          | `queries`, `includeOperations`, `source`   |
| Shortlist nodes     | `get_suggested_nodes`   | `categories`                               |
| Get node info       | `get_node`              | `nodeIds`, `view`, `includeConfigExamples` |
| Find templates      | `search_templates`      | `searchMode`, `query`, `nodeTypes`         |
| Create workflow     | `n8n_create_workflow`   | `name`, `nodes`, `connections`             |
| Validate            | `n8n_validate_workflow` | `id`                                       |
| Auto-fix            | `n8n_autofix_workflow`  | `id`, `applyFixes`                         |
| Test (self-healing) | `n8n_trigger_execution` | `id`                                       |
| Test (external)     | `n8n_test_workflow`     | `workflowId`                               |
| Debug               | `n8n_manage_executions` | `action`, `id`, `mode`                     |
| Mock data           | `n8n_manage_pindata`    | `mode`, `id`, `nodeName`                   |

## Next Steps

<CardGroup cols="2">
  <Card title="Explore All Tools" icon="toolbox" href="/agent-tools">
    See the complete reference for all 23 active Synta MCP tools
  </Card>

  <Card title="Configure Agent Rules" icon="sliders" href="/rules">
    Set up client-specific rules for optimal workflow building
  </Card>
</CardGroup>