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

# Tools Overview

Enable agents to interact with external systems and perform actions.

***

## Overview

Tools are the functional extensions of an agent's intelligence—they enable agents to go beyond conversation by interacting with third-party applications, retrieving information, performing logic-based operations, and triggering workflows across complex environments.

Powered by the tool invocation capabilities of LLMs, agents can dynamically identify and invoke the most relevant tools at runtime, ensuring flexibility, scalability, and precision in task execution.

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

**Example — Leave Managing Agent:**

| Tool              | Purpose                                                                |
| ----------------- | ---------------------------------------------------------------------- |
| Get Leave Balance | Invokes an external API to retrieve leave details                      |
| Leave Application | Gathers necessary information and applies leaves in the backend system |

**Example — Credit Card Assistant:**

| Tool                        | Purpose                                           |
| --------------------------- | ------------------------------------------------- |
| Retrieve Outstanding Amount | Fetches the current due amount                    |
| Fetch Credit Limit          | Retrieves the user's maximum credit limit         |
| Initiate Bill Payment       | Initiates the bill payment process                |
| Find Recent Transactions    | Displays recent user transactions from a database |

## Tool Types

The Platform supports three tool types, each serving a different purpose—from orchestrating visual workflows to executing custom scripts or invoking remote services.

* [**Workflow Tools**](/agent-platform/tools/workflow): Visual, no-code tools built with drag-and-drop. Best for well-defined, traceable processes.
* [**Code Tools**](/agent-platform/tools/code): Custom JavaScript or Python functions. Best for complex logic and dynamic processing.
* [**MCP Tools**](/agent-platform/tools/mcp): Remote functions via Model Context Protocol. Best for enterprise integrations and shared toolsets.

## Quick Comparison

| Aspect      | Workflow          | Code             | MCP               |
| ----------- | ----------------- | ---------------- | ----------------- |
| Interface   | Visual builder    | Code editor      | Server config     |
| Languages   | No-code           | JS, Python       | Protocol-based    |
| Best for    | Defined processes | Custom logic     | External services |
| Deployment  | API endpoint      | Inline execution | Remote server     |
| Skill level | Low               | Medium-High      | Medium            |

## Tool Types in Detail

### Workflow Tools

Workflow Tools provide a visual, no-code interface for designing and orchestrating agent actions. Built for clarity and control, they let you define multi-step workflows using an intuitive graphical builder—ideal for standardized, repeatable processes. They support both synchronous and asynchronous execution modes.

**Best suited for:** Scenarios where business logic is consistent, well-defined, and benefits from visual traceability.

| Example             | What it does                                       |
| ------------------- | -------------------------------------------------- |
| Weather API tool    | Retrieves live weather updates                     |
| Stock Market tool   | Fetches real-time stock prices                     |
| Database Query tool | Accesses structured data from a company's database |

### Code Tools

Code Tools provide maximum flexibility by enabling agents to run custom JavaScript or Python code. They are ideal for handling dynamic logic, conditional processing, or integrations that can't be captured through pre-defined workflows. Code Tools support synchronous execution and are best when precision, extensibility, or complex algorithms are required.

**Best suited for:** Advanced use cases involving business-specific logic, data transformation, or interaction with complex systems.

| Example             | What it does                                          |
| ------------------- | ----------------------------------------------------- |
| SQL Query Processor | Executes SQL queries on a specified database          |
| Custom Validator    | Validates inputs using custom logic before proceeding |

### MCP Tools

MCP Tools connect agents to remote functions hosted on Model Context Protocol (MCP) servers. Following a client-server discovery model, agents can dynamically invoke third-party or proprietary services in real time without embedding logic directly into workflows or code.

Once connected, MCP Tools can be selected, configured, versioned, and managed independently—allowing modular and scalable integration across environments. Because they are centrally managed, they support versioning, cross-feature reuse, and simplified development.

**Best suited for:** Seamless integration with external APIs, proprietary platforms, or shared toolsets across teams or organizations.

| Example                  | What it does                                              |
| ------------------------ | --------------------------------------------------------- |
| Enterprise HR Toolset    | A suite of HR tools exposed via MCP                       |
| Remote Invoice Processor | Executes billing operations through a secure MCP endpoint |

## How Tool Calling Works

```yaml theme={null}
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.

```yaml theme={null}
name: get_order_status
```

### Description

Explains what the tool does. The LLM uses this to decide when to invoke it.

```yaml theme={null}
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.
```

### Input and Output

<CodeGroup>
  ```yaml Parameters Accepted theme={null}
  parameters:
    order_id:
      type: string
      description: The unique order identifier (for example, ORD-12345)
      required: true

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

  ```yaml Output Returned theme={null}
  output:
    type: object
    properties:
      status:
        type: string
        enum: [pending, processing, shipped, delivered, cancelled]
      tracking_number:
        type: string
      estimated_delivery:
        type: string
        format: date
  ```
</CodeGroup>

***

## Creating Tools

The **Tools** page provides a structured view of all tools in an app, with clear visibility into their types, statuses, and linked agents.

### 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. Once deployed, library tools are accessible across multiple apps and act as templates—when imported into an app, they generate a local copy that can be customized without altering the original.

* Reusable across multiple apps.
* Importing is restricted to deployed tools from the library.
* Changes to the library version do not affect local copies in apps.

### App-Scoped Tools

Created within a specific **Agentic App**, or imported from the library into an app. Any modifications apply only to the local copy and do not affect the library version. Changes take effect only after the tool is deployed within the 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.

```yaml theme={null}
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