Tool Integration & Execution

Relevant source files

• apps/sim/app/api/billing/update-cost/route.ts
• apps/sim/app/api/function/execute/route.test.ts
• apps/sim/app/api/function/execute/route.ts
• apps/sim/app/api/wand/route.ts
• apps/sim/app/api/workflows/[id]/log/route.ts
• apps/sim/executor/dag/construction/paths.ts
• apps/sim/executor/handlers/function/function-handler.test.ts
• apps/sim/executor/handlers/function/function-handler.ts
• apps/sim/executor/utils/output-filter.ts
• apps/sim/executor/utils/start-block.test.ts
• apps/sim/executor/utils/start-block.ts
• apps/sim/executor/variables/resolver.ts
• apps/sim/executor/variables/resolvers/block.test.ts
• apps/sim/executor/variables/resolvers/block.ts
• apps/sim/executor/variables/resolvers/reference.ts
• apps/sim/lib/billing/core/usage-log.ts
• apps/sim/lib/core/security/input-validation.server.ts
• apps/sim/lib/core/security/input-validation.test.ts
• apps/sim/lib/core/security/input-validation.ts
• apps/sim/lib/execution/isolated-vm-worker.cjs
• apps/sim/lib/guardrails/validate_regex.ts
• apps/sim/lib/logs/execution/logger.test.ts
• apps/sim/lib/logs/execution/logger.ts
• apps/sim/lib/logs/execution/logging-factory.ts
• apps/sim/lib/logs/execution/logging-session.ts
• apps/sim/lib/logs/types.ts
• apps/sim/lib/webhooks/rss-polling-service.ts
• apps/sim/tools/function/execute.test.ts
• apps/sim/tools/function/execute.ts
• apps/sim/tools/function/types.ts
• apps/sim/tools/hubspot/list_lists.ts
• apps/sim/tools/index.test.ts
• apps/sim/tools/index.ts
• apps/sim/tools/perplexity/chat.ts
• apps/sim/tools/types.ts

This document describes the tool execution infrastructure in Sim: how tools are invoked during workflow execution, parameter merging and validation, credential resolution, SSRF protection, retry logic, and response handling. The executeTool function is the central execution point for all tool types.

For tool configuration and parameter schemas, see Tool Registry System (4.2). For agent-specific tool usage, see Agent Block (4.4). For tool parameter configuration UI, see SubBlock Configuration System (4.5).

Overview

The executeTool function at apps/sim/tools/index.ts225-536 is the unified execution interface for all tools in Sim. It handles:

• Tool ID normalization: Strips resource-specific suffixes (e.g., workflow_executor_<uuid> → workflow_executor) apps/sim/tools/index.ts233-238
• Credential resolution: Fetches OAuth access tokens for authenticated tools or injects hosted API keys for billable services apps/sim/tools/index.ts302-395
• Parameter validation: Validates required parameters after user/LLM merge via validateRequiredParametersAfterMerge apps/sim/tools/utils.ts155-183
• Request execution: Routes to direct execution, internal APIs, or external URLs with SSRF protection apps/sim/tools/index.ts807-836
• Retry logic: Automatic retries for transient failures and rate limits with exponential backoff apps/sim/tools/index.ts171-210
• Post-processing: Applies tool-specific transformations and file hydration via postProcess apps/sim/tools/index.ts466-476

Tool Execution Methods

Method	Use Case	Implementation
Direct execution	In-process tools	tool.directExecution(params) apps/sim/tools/index.ts420-424
Internal route	Platform APIs	Routes to /api/function/execute or /api/mcp/tools/execute apps/sim/tools/index.ts709-727
External URL	Third-party services	OAuth-protected APIs or public endpoints via secureFetchWithPinnedIP apps/sim/tools/index.ts807-836

Sources: apps/sim/tools/index.ts225-536 apps/sim/tools/utils.ts84-135

Tool Execution Pipeline

The execution pipeline bridges natural language intent (from Agents) or workflow structure to concrete code entities.

Diagram: executeTool() Function Flow

1. Tool ID Normalization: Strips resource-specific suffixes apps/sim/tools/index.ts233-238
2. Special Case Handling: load_skill for agent progressive disclosure via resolveSkillContent apps/sim/tools/index.ts243-265
3. Tool Resolution:
   • Custom tools: getToolAsync() fetches from DB apps/sim/tools/utils.ts5-6
   • MCP tools: executeMcpTool() routes to /api/mcp/tools/execute apps/sim/tools/index.ts1091-1197
   • Built-in tools: getTool() from in-memory registry apps/sim/tools/utils.ts32
4. Hosted Key Injection: Checks for Bring Your Own Key (BYOK) first via getBYOKKey, then falls back to Sim-hosted keys with rate limiting apps/sim/tools/index.ts50-138
5. Parameter Validation: Ensures all required user-or-llm parameters are present apps/sim/tools/utils.ts155-183
6. Execution: Routes to direct execution or HTTP request via executeToolRequest apps/sim/tools/index.ts699-1013

Sources: apps/sim/tools/index.ts225-536 apps/sim/tools/utils.ts32-35 apps/sim/tools/index.ts50-138

Hosted Key Injection & BYOK

Sim allows tools to use hosted API keys (e.g., Perplexity, Serper) if the user has not provided their own.

• BYOK (Bring Your Own Key): The system first checks for workspace-level keys using getBYOKKey apps/sim/tools/index.ts67-74 These are used without billing the user's Sim account.
• Hosted Key Rate Limiting: If no BYOK key is found, it uses getHostedKeyRateLimiter().acquireKey() apps/sim/tools/index.ts81-95
• Throttling: If a workspace exceeds the hosted key quota, a 429 error is thrown and a hostedKeyUserThrottled event is emitted apps/sim/tools/index.ts97-117

Sources: apps/sim/tools/index.ts50-138 apps/sim/lib/api-key/byok.ts

SSRF Protection & Secure Fetch

For external tool requests, Sim implements multi-layer protection against Server-Side Request Forgery (SSRF) in apps/sim/lib/core/security/input-validation.server.ts.

Diagram: SSRF Protection Layer

• DNS Validation: validateUrlWithDNS ensures the target URL does not resolve to local or private network addresses (e.g., 127.0.0.1, 169.254.169.254) apps/sim/tools/index.ts9-10
• IP Pinning: secureFetchWithPinnedIP performs the fetch using the pre-validated IP to prevent DNS rebinding attacks where the hostname resolution changes between validation and execution apps/sim/tools/index.ts8
• Path Segment Validation: validatePathSegment blocks directory traversal patterns like ../ or null bytes apps/sim/lib/core/security/input-validation.ts50-160

Sources: apps/sim/lib/core/security/input-validation.ts apps/sim/tools/index.ts8-10

Retry Logic & Rate Limit Handling

Sim implements sophisticated retry logic for both hosted keys and upstream tool APIs in apps/sim/tools/index.ts.

• Rate Limit Detection: isRateLimitError checks for HTTP 429/503 or specific error messages like "insufficient_quota" apps/sim/tools/index.ts144-157
• Exponential Backoff: executeWithRetry uses a base delay (default 1000ms) multiplied by 2^attempt apps/sim/tools/index.ts171-206
• Telemetry: Tracks hostedKeyRateLimited and hostedKeyUserThrottled events to monitor provider health and user usage apps/sim/tools/index.ts202-210

Sources: apps/sim/tools/index.ts144-223 apps/sim/tools/types.ts27-28

Logging & Cost Tracking

Every tool execution is tracked for logging and billing purposes.

• Execution Logging: ExecutionLogger records the start and end of tool calls, including duration, status, and input/output apps/sim/lib/logs/execution/logger.ts51-60
• Cost Calculation: For AI-related tools (like wand or perplexity), usage is recorded via recordUsage and billed against the user's workspace apps/sim/app/api/wand/route.ts137-151
• Trace Spans: Tool calls are aggregated into TraceSpan objects for visualization in the execution timeline apps/sim/lib/logs/types.ts204-234

Sources: apps/sim/lib/logs/execution/logger.ts apps/sim/lib/logs/types.ts apps/sim/app/api/billing/update-cost/route.ts

Parameter Merging & Validation

Before execution, parameters from the LLM and the User (defined in the workflow) are merged.

• Precedence: User-provided values always override LLM-generated values apps/sim/tools/utils.ts84-135
• Visibility: Parameters are categorized as user-only, llm-only, or user-or-llm to determine which entity can provide the value apps/sim/tools/types.ts54-59
• Final Validation: validateRequiredParametersAfterMerge is the last check before execution, ensuring all required parameters are present regardless of their source apps/sim/tools/utils.ts155-183

Sources: apps/sim/tools/utils.ts84-183 apps/sim/tools/types.ts54-59