Skip to main content

​
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:

Deterministic actions

You know exactly which tool to call and with what parameters. No decision-making needed.Example: “Send an email to [email protected] with subject ‘Report Ready’”

Predictable operations

The action is the same every time, just with different data.Example: “Create a calendar event with these specific details”

No interpretation needed

The input data directly maps to tool parameters without reasoning.Example: “Execute SQL query with these parameters”

Performance-critical paths

You need the fastest possible execution without LLM overhead.Example: “Log this event to the monitoring system”

​
Use Agent node with tools when:

Decision-making required

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”

Dynamic tool selection

Multiple tools are available and the right one depends on context.Example: “Fix this issue using whatever tools are necessary”

Interpretation needed

The agent must interpret natural language intent into tool parameters.Example: “Schedule a meeting with the team next week”

Multi-step reasoning

The agent needs to call multiple tools in sequence based on previous results.Example: “Find this information, then format it and send it”
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.

​
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": "{{trigger.input.recipient_email}}",
  "subject": "Analysis Complete: {{document_agent.output.document_type}}",
  "body": "{{report_agent.output.summary}}",
  "attachments": ["{{document_url}}"]
}
Example: Create calendar event tool 
{
  "title": "Review Meeting: {{compliance_agent.output.document_id}}",
  "start_time": "{{trigger.input.meeting_time}}",
  "duration_minutes": 30,
  "attendees": ["{{trigger.input.reviewer_email}}", "{{trigger.input.manager_email}}"],
  "description": "{{compliance_agent.output.findings}}"
}
Example: Database query tool 
{
  "query": "INSERT INTO processed_documents (id, status, risk_score) VALUES ($1, $2, $3)",
  "parameters": [
    "{{document_agent.output.document_id}}",
    "processed",
    "{{risk_agent.output.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.output.message_id}}",
  "timestamp": "{{tool.output.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
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.

​
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": "{{trigger.input.requester_email}}",
    "subject": "Document Processing Complete",
    "body": "Your document has been processed.\n\nDocument: {{document_agent.output.document_name}}\nStatus: {{document_agent.output.status}}\nRisk Score: {{risk_agent.output.risk_score}}\n\nView full report: {{report_url}}",
    "reply_to": "[email protected]"
  },
  "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.output.document_name}}",
    "start_time": "{{trigger.input.review_date}}",
    "end_time": "{{trigger.input.review_date_end}}",
    "attendees": [
      "{{trigger.input.compliance_officer}}",
      "{{trigger.input.document_owner}}",
      "{{trigger.input.manager}}"
    ],
    "description": "Review required for:\n\n{{compliance_agent.output.findings}}\n\nRisk Score: {{compliance_agent.output.risk_score}}",
    "location": "Conference Room A",
    "reminders": [
      {"method": "email", "minutes": 1440},
      {"method": "popup", "minutes": 30}
    ]
  },
  "output": {
    "event_id": "{{tool.output.event_id}}",
    "event_url": "{{tool.output.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.output.status}}",
      "{{risk_agent.output.risk_score}}",
      "NOW()",
      "{{approval_agent.output.decision_rationale}}",
      "{{trigger.input.application_id}}"
    ]
  },
  "output": {
    "rows_affected": "{{tool.output.rows_affected}}",
    "update_successful": "{{tool.output.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/{{trigger.input.customer_id}}",
    "headers": {
      "Authorization": "Bearer {{env.CRM_API_KEY}}",
      "Content-Type": "application/json"
    }
  },
  "output": {
    "customer_name": "{{tool.output.body.name}}",
    "customer_tier": "{{tool.output.body.tier}}",
    "account_manager": "{{tool.output.body.account_manager_email}}",
    "credit_limit": "{{tool.output.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:
Tools that can be safely retried without side effects.Examples: Database reads, API GET requests, file readsStrategy: Aggressive retries with exponential backoff
{
  "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

If you can hard-code the tool call parameters, use a Tool node. This avoids the overhead and unpredictability of agent reasoning.
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.
Don’t assume tools always succeed. Use Condition nodes to check tool outputs and route to error handling when needed.
Different tools have different performance characteristics. Database queries might complete in milliseconds, while external API calls might take seconds.
Store tool outputs in the variable store with descriptive names. This helps with debugging and provides audit trails.
When available, use idempotency keys for non-idempotent operations. This makes retries safe and prevents duplicate actions.
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.

​
Next steps

Agent node

Learn when to use agents vs tools

Condition node

Route based on tool execution results

Human task node

Add human review for failed tool executions

Memory system

Store and access tool outputs across the workflow