Skip to main content

​
Tools

Enable agents to interact with external systems and perform actions.

​
Overview

Tools are capabilities that empower agents to go beyond conversation—they can retrieve data, execute logic, trigger workflows, and interact with third-party services. When an agent needs to take action, it:
  1. Identifies the appropriate tool based on the task
  2. Prepares the required parameters
  3. Invokes the tool through the platform
  4. Processes the results
  5. Incorporates the output into its response

​
Tool Types

​
Workflow Tools

Visual, no-code tools built with drag-and-drop. Best for well-defined, traceable processes.

​
Code Tools

Custom JavaScript or Python functions. Best for complex logic and dynamic processing.

​
MCP Tools

Remote functions via Model Context Protocol. Best for enterprise integrations and shared toolsets.

​
Quick Comparison

AspectWorkflowCodeMCP
InterfaceVisual builderCode editorServer config
LanguagesNo-codeJS, PythonProtocol-based
Best forDefined processesCustom logicExternal services
DeploymentAPI endpointInline executionRemote server
Skill levelLowMedium-HighMedium

​
How Tool Calling Works

User: "What's the weather in Tokyo?"

1. Agent receives request
   └─ Identifies need for external data

2. Tool selection
   └─ Matches "weather" to get_weather tool

3. Parameter preparation
   └─ Extracts: { "location": "Tokyo" }

4. Tool invocation
   └─ Platform calls the tool API

5. Execution
   └─ Tool fetches weather data

6. Result processing
   └─ Returns: { "temp": 22, "condition": "Sunny" }

7. Response generation
   └─ Agent: "It's currently 22°C and sunny in Tokyo."

​
Tool Anatomy

Every tool has these components:

​
Name

A unique identifier used in tool selection. 
name: get_order_status

​
Description

Explains what the tool does. The LLM uses this to decide when to invoke it. 
description: |
  Retrieves the current status of a customer order including
  shipping information, estimated delivery date, and tracking number.
  Use when customers ask about their order status.

​
Parameters

The inputs the tool accepts. 
parameters:
  order_id:
    type: string
    description: The unique order identifier (e.g., ORD-12345)
    required: true

  include_history:
    type: boolean
    description: Whether to include status change history
    required: false
    default: false

​
Output

What the tool returns. 
output:
  type: object
  properties:
    status:
      type: string
      enum: [pending, processing, shipped, delivered, cancelled]
    tracking_number:
      type: string
    estimated_delivery:
      type: string
      format: date

​
Creating Tools

​
Option 1: Create New

Build a tool from scratch for your specific needs.
  1. Navigate to Tools in your app or the tools library
  2. Click + New Tool
  3. Select tool type (Workflow, Code, or MCP)
  4. Configure name, description, and parameters
  5. Build the tool logic
  6. Test and deploy

​
Option 2: Import Existing

Reuse tools from the library or import from files.
  1. Click Import Tool
  2. Upload a .zip file containing:
    • flow_definition.json (required)
    • app_definition.json (optional)
    • env_variables.json (optional)
  3. Review and configure
  4. Deploy

​
Tool Scopes

​
Library Tools

Created in the Tools section, independent of any app.
  • Reusable across multiple apps
  • Changes affect all linked apps
  • Best for shared functionality

​
App-Scoped Tools

Created within a specific Agentic App.
  • Isolated to that app
  • Changes don’t affect library versions
  • Best for app-specific logic

​
Linking Tools to Agents

  1. Open your agent configuration
  2. Navigate to Tools
  3. Click + Add Tool
  4. Choose:
    • Create new — Build app-specific tool
    • Link existing — Connect library tool
    • Import — Upload tool definition
  5. Configure tool access and permissions

​
Execution Modes

​
Synchronous

Tool executes immediately, agent waits for response. 
Request → Execute → Response → Continue
Use for: Real-time lookups, quick calculations, instant validations.

​
Asynchronous

Tool executes in background, agent continues or waits for callback. 
Request → Queue → (Agent continues) → Callback → Update
Use for: Long-running processes, batch operations, external approvals.

​
Deployment

After building a tool, deploy it to make it available.

​
Sync Endpoint

POST /api/v1/tools/{tool_id}/execute
Content-Type: application/json

{
  "parameters": {
    "order_id": "ORD-12345"
  }
}

​
Async Poll Endpoint

POST /api/v1/tools/{tool_id}/execute/async
Content-Type: application/json

{
  "parameters": {
    "order_id": "ORD-12345"
  }
}

Response:
{
  "execution_id": "exec_abc123",
  "status": "pending"
}

GET /api/v1/tools/{tool_id}/executions/{execution_id}

​
Async Push (Webhook)

Configure a webhook URL to receive results when ready.

​
Security

​
API Keys

Tools are secured with API keys for external access. 
headers:
  Authorization: Bearer sk-tool-xxxxx

​
Role-Based Access

Control who can:
  • View tool configurations
  • Edit tool logic
  • Deploy tools
  • Access execution logs

​
PII Protection

Tools inherit app-level PII protection:
  • Input scanning for sensitive patterns
  • Automatic masking in logs
  • Secure internal access when needed

​
Testing Tools

Before deployment, validate tool behavior:
  1. Open the tool details page
  2. Click Test
  3. Provide sample input parameters
  4. Review execution results
  5. Check for errors and edge cases

​
Monitoring

Track tool performance with:
  • Execution history — Success/failure rates
  • Response times — Latency metrics
  • Token usage — For AI-powered tools
  • Audit logs — Who changed what, when