Tool node

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:

Use Agent node with tools when:

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

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

Example: Create calendar event tool

{
  "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

{
  "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:

{
  "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

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "retry": {
    "max_attempts": 5,
    "backoff": "exponential",
    "initial_interval": "1s",
    "max_interval": "60s"
  }
}

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

Next steps