> ## Documentation Index
> Fetch the complete documentation index at: https://helpcenter.magure.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool node

> Execute MCP tools directly in workflows without agent reasoning for deterministic actions

## Purpose

The **Tool node** executes an MCP tool directly as a workflow step — without agent reasoning. Use Tool nodes when you know exactly which tool to call and with what parameters. No AI decision-making, just deterministic tool execution.

Tool nodes provide predictable, repeatable actions: send this email, create this calendar event, query this database, call this API. They're the programmatic actions within your AI workflows.

## When to use Tool node vs Agent node with tools

Understanding when to use each approach is critical for building effective workflows.

### Use Tool node when:

<CardGroup cols={1}>
  <Card title="Deterministic actions" icon="check">
    You know exactly which tool to call and with what parameters. No decision-making needed.

    **Example:** "Send an email to [john@company.com](mailto:john@company.com) with subject 'Report Ready'"
  </Card>

  <Card title="Predictable operations" icon="check">
    The action is the same every time, just with different data.

    **Example:** "Create a calendar event with these specific details"
  </Card>

  <Card title="No interpretation needed" icon="check">
    The input data directly maps to tool parameters without reasoning.

    **Example:** "Execute SQL query with these parameters"
  </Card>

  <Card title="Performance-critical paths" icon="check">
    You need the fastest possible execution without LLM overhead.

    **Example:** "Log this event to the monitoring system"
  </Card>
</CardGroup>

### Use Agent node with tools when:

<CardGroup cols={1}>
  <Card title="Decision-making required" icon="robot">
    The agent needs to decide which tool(s) to call based on reasoning.

    **Example:** "Research this topic and use the appropriate tools to find answers"
  </Card>

  <Card title="Dynamic tool selection" icon="robot">
    Multiple tools are available and the right one depends on context.

    **Example:** "Fix this issue using whatever tools are necessary"
  </Card>

  <Card title="Interpretation needed" icon="robot">
    The agent must interpret natural language intent into tool parameters.

    **Example:** "Schedule a meeting with the team next week"
  </Card>

  <Card title="Multi-step reasoning" icon="robot">
    The agent needs to call multiple tools in sequence based on previous results.

    **Example:** "Find this information, then format it and send it"
  </Card>
</CardGroup>

<Tip>
  **Rule of thumb:** If you can write the exact tool call with specific parameters, use a Tool node. If you need AI to figure out what to do, use an Agent node.
</Tip>

## Configuration

Configure a Tool node to execute the right MCP tool with the right parameters.

### Select an MCP tool

Choose which tool to execute from your available MCP connections. MagOneAI supports any MCP-compliant tool:

* **Communication tools** — Email, Slack, SMS, notifications
* **Calendar tools** — Google Calendar, Outlook, event scheduling
* **Database tools** — PostgreSQL, MongoDB, Redis queries
* **API tools** — REST API calls, webhooks, external services
* **File tools** — S3 uploads, file operations, document processing
* **CRM tools** — Salesforce, HubSpot, customer data
* **Custom tools** — Your own MCP server implementations

The available tools depend on your MCP server connections configured in MagOneAI Studio.

### Input parameter mapping

Map data from the variable store to the tool's input parameters. Each tool has a defined schema for its parameters.

**Example: Send email tool**

```json theme={null}
{
  "to": "{{input.recipient_email}}",
  "subject": "Analysis Complete: {{document_agent.document_type}}",
  "body": "{{report_agent.summary}}",
  "attachments": ["{{document_url}}"]
}
```

**Example: Create calendar event tool**

```json theme={null}
{
  "title": "Review Meeting: {{compliance_agent.document_id}}",
  "start_time": "{{input.meeting_time}}",
  "duration_minutes": 30,
  "attendees": ["{{input.reviewer_email}}", "{{input.manager_email}}"],
  "description": "{{compliance_agent.findings}}"
}
```

**Example: Database query tool**

```json theme={null}
{
  "query": "INSERT INTO processed_documents (id, status, risk_score) VALUES ($1, $2, $3)",
  "parameters": [
    "{{document_agent.document_id}}",
    "processed",
    "{{risk_agent.risk_score}}"
  ]
}
```

### Output mapping

Define how the tool's response is stored in the variable store. Tool responses vary by tool type:

* **Email tools** — Confirmation, message ID
* **Calendar tools** — Event ID, event URL
* **Database tools** — Query results, affected rows
* **API tools** — Response body, status code

**Example output mapping:**

```json theme={null}
{
  "email_sent": true,
  "message_id": "{{tool.message_id}}",
  "timestamp": "{{tool.sent_at}}"
}
```

### Retry and timeout settings

Configure resilience for tool execution:

* **Retry count** — Number of retry attempts on failure
* **Retry backoff** — Delay strategy between retries (fixed or exponential)
* **Timeout** — Maximum execution time before the tool call is cancelled
* **Retry on errors** — Which error types trigger retries (network errors, rate limits, timeouts)

Different tools need different retry strategies:

* **Email/notifications** — Retry aggressively (3-5 retries with exponential backoff)
* **Database writes** — Retry cautiously to avoid duplicates
* **External APIs** — Respect rate limits, use exponential backoff

<Warning>
  Be careful with retry logic for tools that have side effects. Retrying a "send email" tool may send duplicate emails. Use idempotency keys or check-before-action patterns when appropriate.
</Warning>

## Examples

Let's look at practical examples of Tool nodes in real workflows.

### Example 1: Send notification after workflow completion

**Scenario:** After a document processing workflow completes, send an email notification to the requester with the results.

**Tool node configuration:**

```json theme={null}
{
  "tool": "gmail_send_email",
  "input": {
    "to": "{{input.requester_email}}",
    "subject": "Document Processing Complete",
    "body": "Your document has been processed.\n\nDocument: {{document_agent.document_name}}\nStatus: {{document_agent.status}}\nRisk Score: {{risk_agent.risk_score}}\n\nView full report: {{report_url}}",
    "reply_to": "noreply@company.com"
  },
  "retry": {
    "max_attempts": 3,
    "backoff": "exponential"
  },
  "timeout": "30s"
}
```

This is a perfect use case for a Tool node: you know exactly what to send and to whom, no reasoning needed.

### Example 2: Create calendar event with specific details

**Scenario:** After a compliance review identifies issues, automatically schedule a review meeting with the appropriate stakeholders.

**Tool node configuration:**

```json theme={null}
{
  "tool": "google_calendar_create_event",
  "input": {
    "calendar_id": "primary",
    "title": "Compliance Review: {{document_agent.document_name}}",
    "start_time": "{{input.review_date}}",
    "end_time": "{{input.review_date_end}}",
    "attendees": [
      "{{input.compliance_officer}}",
      "{{input.document_owner}}",
      "{{input.manager}}"
    ],
    "description": "Review required for:\n\n{{compliance_agent.findings}}\n\nRisk Score: {{compliance_agent.risk_score}}",
    "location": "Conference Room A",
    "reminders": [
      {"method": "email", "minutes": 1440},
      {"method": "popup", "minutes": 30}
    ]
  },
  "output": {
    "event_id": "{{tool.event_id}}",
    "event_url": "{{tool.html_link}}"
  }
}
```

### Example 3: Execute database query with known parameters

**Scenario:** After processing a customer application, update the database with the results.

**Tool node configuration:**

```json theme={null}
{
  "tool": "postgres_execute",
  "input": {
    "query": "UPDATE applications SET status = $1, risk_score = $2, processed_at = $3, processor_notes = $4 WHERE application_id = $5",
    "parameters": [
      "{{approval_agent.status}}",
      "{{risk_agent.risk_score}}",
      "NOW()",
      "{{approval_agent.decision_rationale}}",
      "{{input.application_id}}"
    ]
  },
  "output": {
    "rows_affected": "{{tool.rows_affected}}",
    "update_successful": "{{tool.rows_affected > 0}}"
  },
  "retry": {
    "max_attempts": 2,
    "backoff": "fixed"
  }
}
```

### Example 4: Fetch data from external API

**Scenario:** Look up customer information from a CRM system before processing their request.

**Tool node configuration:**

```json theme={null}
{
  "tool": "http_request",
  "input": {
    "method": "GET",
    "url": "https://api.crm.com/v1/customers/{{input.customer_id}}",
    "headers": {
      "Authorization": "Bearer {{env.CRM_API_KEY}}",
      "Content-Type": "application/json"
    }
  },
  "output": {
    "customer_name": "{{tool.body.name}}",
    "customer_tier": "{{tool.body.tier}}",
    "account_manager": "{{tool.body.account_manager_email}}",
    "credit_limit": "{{tool.body.credit_limit}}"
  },
  "retry": {
    "max_attempts": 3,
    "backoff": "exponential",
    "retry_on": ["network_error", "timeout", "rate_limit"]
  },
  "timeout": "10s"
}
```

## Error handling

Tool executions can fail for many reasons: network issues, API rate limits, invalid parameters, authentication failures. Proper error handling ensures workflow resilience.

### Retry strategies

Configure retries based on the tool's characteristics:

<Tabs>
  <Tab title="Idempotent tools">
    Tools that can be safely retried without side effects.

    **Examples:** Database reads, API GET requests, file reads

    **Strategy:** Aggressive retries with exponential backoff

    ```json theme={null}
    {
      "retry": {
        "max_attempts": 5,
        "backoff": "exponential",
        "initial_interval": "1s",
        "max_interval": "60s"
      }
    }
    ```
  </Tab>

  <Tab title="Non-idempotent tools">
    Tools that have side effects and shouldn't be retried automatically.

    **Examples:** Email sending, payment processing, database writes without idempotency keys

    **Strategy:** Limited retries, manual review on failure

    ```json theme={null}
    {
      "retry": {
        "max_attempts": 1,
        "backoff": "none"
      }
    }
    ```
  </Tab>

  <Tab title="Rate-limited tools">
    Tools that may hit API rate limits.

    **Examples:** External APIs, social media tools

    **Strategy:** Exponential backoff with jitter

    ```json theme={null}
    {
      "retry": {
        "max_attempts": 4,
        "backoff": "exponential",
        "initial_interval": "2s",
        "max_interval": "120s",
        "retry_on": ["rate_limit", "timeout"]
      }
    }
    ```
  </Tab>
</Tabs>

### Fallback patterns

Use Condition nodes after Tool nodes to handle failures gracefully:

1. **Tool execution** — Attempt the primary action
2. **Condition check** — Did the tool succeed?
3. **Success path** — Continue the workflow
4. **Failure path** — Execute fallback logic (alternative tool, human task, error notification)

**Example:**

```
[Send Email Tool] → [Condition: email_sent == true]
   ├─ True → [Continue workflow]
   └─ False → [Send Slack Notification] → [Human Task: Review]
```

## Best practices

<AccordionGroup>
  <Accordion title="Use Tool nodes for known actions">
    If you can hard-code the tool call parameters, use a Tool node. This avoids the overhead and unpredictability of agent reasoning.
  </Accordion>

  <Accordion title="Validate inputs before tool execution">
    Use Condition nodes to validate that required data exists and is in the correct format before calling tools. This prevents tool failures due to invalid inputs.
  </Accordion>

  <Accordion title="Handle errors explicitly">
    Don't assume tools always succeed. Use Condition nodes to check tool outputs and route to error handling when needed.
  </Accordion>

  <Accordion title="Set realistic timeouts">
    Different tools have different performance characteristics. Database queries might complete in milliseconds, while external API calls might take seconds.
  </Accordion>

  <Accordion title="Log tool executions">
    Store tool outputs in the variable store with descriptive names. This helps with debugging and provides audit trails.
  </Accordion>

  <Accordion title="Use idempotency keys">
    When available, use idempotency keys for non-idempotent operations. This makes retries safe and prevents duplicate actions.
  </Accordion>
</AccordionGroup>

<Tip>
  Combine Tool nodes with Agent nodes for powerful hybrid workflows. Let agents make decisions and handle complexity, then use Tool nodes to execute the resulting actions deterministically.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Agent node" icon="robot" href="/workflows/agent-node">
    Learn when to use agents vs tools
  </Card>

  <Card title="Condition node" icon="code-branch" href="/workflows/condition-node">
    Route based on tool execution results
  </Card>

  <Card title="Human task node" icon="user-check" href="/workflows/human-task-node">
    Add human review for failed tool executions
  </Card>

  <Card title="Memory system" icon="database" href="/workflows/memory">
    Store and access tool outputs across the workflow
  </Card>
</CardGroup>